Update javadoc for the NestingRulesProvider interface

platform/lang-api/src/com/intellij/ide/projectView/NestingRulesProvider.java

@@ -18,16 +18,25 @@ package com.intellij.ide.projectView;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This interface is intended for a provider of nesting rules for the project view.
- * Implementations of the {@link #addFileNestingRules} method should pass
- * the longest possible file name suffix to the consumer.
- * Usually this suffix starts with a dot. For example ".js"->".min.js".
+ * This interface is intended to provide file nesting rules,
+ * which allow to improve folder contents presentation in the project view
+ * by showing some files as children of another peer file.
+ * It is useful when a folder contains both source file and its compiled output.
+ * For example, a generated {@code foo.min.js} file will be shown
+ * as a child of a {@code foo.js} file.
+ * <br/>Note that nesting logic is based on file names only.<br/>
  * You can specify a custom provider in the {@code plugin.xml} file:<pre>
  * &lt;extensions defaultExtensionNs="com.intellij"&gt;
  * &nbsp;&nbsp;&nbsp;&nbsp;&lt;projectViewNestingRulesProvider implementation="my.package.MyRulesProvider"/&gt;
  * &lt;/extensions&gt;</pre>
  */
 public interface NestingRulesProvider {
+  /**
+   * Implementations of this method should pass the longest possible file name suffix to the consumer.
+   * Usually this suffix starts with a dot. For example ".js"->".min.js".
+   *
+   * @param consumer a consumer which maps extensions of a parent file and its child
+   */
   void addFileNestingRules(@NotNull Consumer consumer);
 
   interface Consumer {