diff --git a/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java b/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java
index 6c3694d85847..bc81d6034209 100644
--- a/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java
+++ b/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java
@@ -30,6 +30,12 @@ import java.util.Set;
 /**
  * Defines a single folding region in the code.
  *
+ * <p><a name="Dependencies"><b>Dependencies</b></a></p>
+ * Dependencies are objects (in particular, instances of {@link com.intellij.openapi.util.ModificationTracker}), 
+ * which can be tracked for changes, that should trigger folding regions recalculation for an editor (initiating code folding pass). 
+ * Changed dependency for a specific region causes its regeneration according to potentially updated folding rules, 
+ * e.g. with regard to 'collapsed by default' state.
+ * 
  * @author max
  * @see FoldingBuilder
  */
@@ -47,14 +53,17 @@ public class FoldingDescriptor {
    * Creates a folding region related to the specified AST node and covering the specified
    * text range.
    * @param node  The node to which the folding region is related. The node is then passed to
-   *              {@link FoldingBuilder#getPlaceholderText(com.intellij.lang.ASTNode)} and
-   *              {@link FoldingBuilder#isCollapsedByDefault(com.intellij.lang.ASTNode)}.
+   *              {@link FoldingBuilder#getPlaceholderText(ASTNode)} and
+   *              {@link FoldingBuilder#isCollapsedByDefault(ASTNode)}.
    * @param range The folded text range.
    */
   public FoldingDescriptor(@NotNull ASTNode node, @NotNull TextRange range) {
     this(node, range, null);
   }
 
+  /**
+   * @param dependency see <a href="#Dependencies">Dependencies</a>
+   */
   public FoldingDescriptor(@NotNull ASTNode node, @NotNull TextRange range, @Nullable Object dependency) {
     this(node, range, null, dependency);
   }
@@ -63,38 +72,44 @@ public class FoldingDescriptor {
     this(ObjectUtils.assertNotNull(element.getNode()), range, null);
   }
 
+  /**
+   * @param dependency see <a href="#Dependencies">Dependencies</a>
+   */
   public FoldingDescriptor(@NotNull PsiElement element, @NotNull TextRange range, @Nullable Object dependency) {
     this(ObjectUtils.assertNotNull(element.getNode()), range, null, 
-         dependency == null ? Collections.<Object>emptySet() : Collections.singleton(dependency));
+         dependency == null ? Collections.emptySet() : Collections.singleton(dependency));
   }
 
   /**
    * Creates a folding region related to the specified AST node and covering the specified
    * text range.
    * @param node  The node to which the folding region is related. The node is then passed to
-   *              {@link FoldingBuilder#getPlaceholderText(com.intellij.lang.ASTNode)} and
-   *              {@link FoldingBuilder#isCollapsedByDefault(com.intellij.lang.ASTNode)}.
+   *              {@link FoldingBuilder#getPlaceholderText(ASTNode)} and
+   *              {@link FoldingBuilder#isCollapsedByDefault(ASTNode)}.
    * @param range The folded text range.
    * @param group Regions with the same group instance expand and collapse together.
    */
   public FoldingDescriptor(@NotNull ASTNode node, @NotNull TextRange range, @Nullable FoldingGroup group) {
-    this(node, range, group, Collections.<Object>emptySet());
+    this(node, range, group, Collections.emptySet());
   }
 
+  /**
+   * @param dependency see <a href="#Dependencies">Dependencies</a>
+   */
   public FoldingDescriptor(@NotNull ASTNode node, @NotNull TextRange range, @Nullable FoldingGroup group, @Nullable Object dependency) {
-    this(node, range, group, dependency == null ? Collections.<Object>emptySet() : Collections.singleton(dependency));
+    this(node, range, group, dependency == null ? Collections.emptySet() : Collections.singleton(dependency));
   }
 
   /**
    * Creates a folding region related to the specified AST node and covering the specified
    * text range.
    * @param node  The node to which the folding region is related. The node is then passed to
-   *              {@link com.intellij.lang.folding.FoldingBuilder#getPlaceholderText(com.intellij.lang.ASTNode)} and
-   *              {@link com.intellij.lang.folding.FoldingBuilder#isCollapsedByDefault(com.intellij.lang.ASTNode)}.
+   *              {@link FoldingBuilder#getPlaceholderText(ASTNode)} and
+   *              {@link FoldingBuilder#isCollapsedByDefault(ASTNode)}.
    * @param range The folded text range.
    * @param group Regions with the same group instance expand and collapse together.
    * @param dependencies folding dependencies: other files or elements that could change
-   * folding description
+   * folding description, see <a href="#Dependencies">Dependencies</a>
    */
   public FoldingDescriptor(@NotNull ASTNode node, @NotNull TextRange range, @Nullable FoldingGroup group, Set<Object> dependencies) {
     this(node, range, group, dependencies, false);
@@ -104,11 +119,11 @@ public class FoldingDescriptor {
    * Creates a folding region related to the specified AST node and covering the specified
    * text range.
    * @param node  The node to which the folding region is related. The node is then passed to
-   *              {@link com.intellij.lang.folding.FoldingBuilder#getPlaceholderText(com.intellij.lang.ASTNode)} and
-   *              {@link com.intellij.lang.folding.FoldingBuilder#isCollapsedByDefault(com.intellij.lang.ASTNode)}.
+   *              {@link FoldingBuilder#getPlaceholderText(ASTNode)} and
+   *              {@link FoldingBuilder#isCollapsedByDefault(ASTNode)}.
    * @param range The folded text range.
    * @param group Regions with the same group instance expand and collapse together.
-   * @param dependencies folding dependencies: other files or elements that could change
+   * @param dependencies folding dependencies: other files or elements that could change, see <a href="#Dependencies">Dependencies</a>
    * @param neverExpands shall be true for fold regions that must not be ever expanded.
    */
   public FoldingDescriptor(@NotNull ASTNode node,
diff --git a/platform/core-impl/src/com/intellij/lang/folding/NamedFoldingDescriptor.java b/platform/core-impl/src/com/intellij/lang/folding/NamedFoldingDescriptor.java
index 266ce6b5cae2..1e9f48bc25f3 100644
--- a/platform/core-impl/src/com/intellij/lang/folding/NamedFoldingDescriptor.java
+++ b/platform/core-impl/src/com/intellij/lang/folding/NamedFoldingDescriptor.java
@@ -22,6 +22,10 @@ import com.intellij.psi.PsiElement;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * A variant of {@link FoldingDescriptor} which keeps precalculated value of placeholder text. 
+ * This makes 'apply' phase of code folding pass (executed in EDT) faster. 
+ */
 public class NamedFoldingDescriptor extends FoldingDescriptor {
   private final String myPlaceholderText;