PathMacros: more javadocs

diff --git a/platform/projectModel-api/src/com/intellij/openapi/application/PathMacros.java b/platform/projectModel-api/src/com/intellij/openapi/application/PathMacros.java
index fac4e5e9edb14ec2d5ec88bf91b7df37661255fa..17681c6b270f481a32c5ae7fdd6e1d381ef38ecf 100644 (file)
--- a/platform/projectModel-api/src/com/intellij/openapi/application/PathMacros.java
+++ b/platform/projectModel-api/src/com/intellij/openapi/application/PathMacros.java
@@ -21,6 +21,14 @@ import org.jetbrains.annotations.NotNull;
 import java.util.Collection;
 import java.util.Set;
 
+/**
+ * Stores predefined and custom (user-defined) path variables. Path variables are used to convert paths from absolute to portable form and
+ * vice versa. It allows us to reuse project configuration files on different machines.
+ * <p>
+ * In order to make a path (or URL) portable the serialization subsystem replaces its prefix by name of a corresponding path variable.
+ * There are {@link #getSystemMacroNames() predefined path variables} and also it's possible to specify {@link #getUserMacroNames() custom path variables}.
+ * </p>
+ */
 public abstract class PathMacros {
   public static PathMacros getInstance() {
     return ServiceManager.getService(PathMacros.class);

diff --git a/platform/projectModel-impl/src/com/intellij/openapi/components/PathMacroSubstitutor.java b/platform/projectModel-impl/src/com/intellij/openapi/components/PathMacroSubstitutor.java
index 7d2606001b334e3fd0460a94dc80387ca0427ad2..cbbedbb7947a9d3f3cc499b651a11de8bca37d5e 100644 (file)
--- a/platform/projectModel-impl/src/com/intellij/openapi/components/PathMacroSubstitutor.java
+++ b/platform/projectModel-impl/src/com/intellij/openapi/components/PathMacroSubstitutor.java
@@ -18,7 +18,15 @@ package com.intellij.openapi.components;
 import org.jdom.Element;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Provides methods to convert paths from absolute to portable form and vice versa.
+ *
+ * @see com.intellij.openapi.application.PathMacros
+ */
 public interface PathMacroSubstitutor {
+  /**
+   * Convert path to absolute by replacing all names of path variables by its values
+   */
   String expandPath(String path);
 
   @NotNull
@@ -26,24 +34,31 @@ public interface PathMacroSubstitutor {
     return collapsePath(text, false);
   }
 
+  /**
+   * Convert paths inside {@code text} to portable form by replacing all values of path variables by their names.
+   * @param recursively if {@code true} all occurrences of paths inside {@code text} will be processed, otherwise {@code text} will be converted
+   *                    only if its entire content is a path (or URL)
+   */
   String collapsePath(@NotNull String text, boolean recursively);
 
-  void expandPaths(@NotNull Element element);
-
   /**
-   * Path will be collapsed only if the entire content of an attribute (tag text) is a path, if a path is a substring of an attribute value it won't be collapsed.
+   * Process sub tags of {@code element} recursively and convert paths to absolute forms in all tag texts and attribute values.
    */
+  void expandPaths(@NotNull Element element);
+
   default void collapsePaths(@NotNull Element element) {
     collapsePaths(element, false);
   }
 
-  /**
-   * Path will be collapsed even if a path is a substring of an attribute value.
-   */
   default void collapsePathsRecursively(@NotNull Element element) {
     collapsePaths(element, true);
   }
 
+  /**
+   * Process sub tags of {@code element} recursively and convert paths to portable forms in all tag texts and attribute values.
+   * @param recursively if {@code true} all occurrences of paths inside tag texts and attribute values will be processed, otherwise
+   * they will be converted only if their entire content is a path (or URL)
+   */
   void collapsePaths(@NotNull Element element, boolean recursively);
 
   default String collapsePathsRecursively(@NotNull String string) {