diff --git a/platform/indexing-api/src/com/intellij/util/indexing/CompositeDataIndexer.java b/platform/indexing-api/src/com/intellij/util/indexing/CompositeDataIndexer.java
index e3eb87b752ab..0e80e238799f 100644
--- a/platform/indexing-api/src/com/intellij/util/indexing/CompositeDataIndexer.java
+++ b/platform/indexing-api/src/com/intellij/util/indexing/CompositeDataIndexer.java
@@ -3,36 +3,46 @@ package com.intellij.util.indexing;
 
 import com.intellij.util.ObjectUtils;
 import com.intellij.util.io.KeyDescriptor;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Collections;
 import java.util.Map;
 
-
+/**
+ * Represents {@link DataIndexer} which behaviour can be extended by some kind of extension points.
+ *
+ * @see IdIndex, StubUpdatingIndex as an examples
+ */
+@ApiStatus.Experimental
 public interface CompositeDataIndexer<K, V, SubIndexerType, SubIndexerVersion> extends DataIndexer<K, V, FileContent> {
   /**
+   * Calculates sub-indexer type which will be used by indexing algorithm.
+   * Usually SubIndexerType it's some extension which build index for a given file.
+   *
+   * @see CompositeDataIndexer#map(FileContent, Object)
    * @return null if file is not acceptable for indexing
    */
   @Nullable
   SubIndexerType calculateSubIndexer(@NotNull IndexedFile file);
 
   /**
-   * determine should we load content to provide sub-indexer
+   * Determine should we load content to provide sub-indexer.
    */
   default boolean requiresContentForSubIndexerEvaluation(@NotNull IndexedFile file) {
     return false;
   }
 
   /**
-   * Note that sub-indexer serialization algorithm should not depend on the current session or other things.
-   * For example you must not save any unsorted data (ex: HashSet-s) here.
+   * SubIndexerVersion reflects StubIndexerType persistent version.
+   * It should depend only on it and must not use any additional information about IDE setup.
    */
   @NotNull
   SubIndexerVersion getSubIndexerVersion(@NotNull SubIndexerType subIndexerType);
 
   /**
-   * SubIndexerVersion descriptor must depend only on corresponding index version, should be read even SubIndexerType is not available anymore
+   * SubIndexerVersion descriptor must depend only on corresponding index version, should be available to read even corresponding SubIndexerType is not exist anymore.
    */
   @NotNull
   KeyDescriptor<SubIndexerVersion> getSubIndexerVersionDescriptor();
@@ -44,6 +54,9 @@ public interface CompositeDataIndexer<K, V, SubIndexerType, SubIndexerVersion> e
     return subIndexerType == null ? Collections.emptyMap() : map(inputData, ObjectUtils.notNull(subIndexerType));
   }
 
+  /**
+   * @return indexed data for an input provided by indexerType argument
+   */
   @NotNull
   Map<K, V> map(@NotNull FileContent inputData, @NotNull SubIndexerType indexerType);
 }