diff --git a/java/java-indexing-impl/src/com/intellij/compiler/CompilerDirectHierarchyInfo.java b/java/java-indexing-impl/src/com/intellij/compiler/CompilerDirectHierarchyInfo.java
index 5557746a8e83..d21a662f0b67 100644
--- a/java/java-indexing-impl/src/com/intellij/compiler/CompilerDirectHierarchyInfo.java
+++ b/java/java-indexing-impl/src/com/intellij/compiler/CompilerDirectHierarchyInfo.java
@@ -22,7 +22,7 @@ import org.jetbrains.annotations.NotNull;
 import java.util.stream.Stream;
 
 /**
- * represents search result for functional expressions or inheritance hierarchy of given interface/class
+ * represents search result for functional expressions or inheritance hierarchy of given interface/class using indices built on compilation time.
  */
 public interface CompilerDirectHierarchyInfo {
   /**
diff --git a/java/java-indexing-impl/src/com/intellij/compiler/CompilerReferenceService.java b/java/java-indexing-impl/src/com/intellij/compiler/CompilerReferenceService.java
index 0459aae0d45e..909d749396b8 100644
--- a/java/java-indexing-impl/src/com/intellij/compiler/CompilerReferenceService.java
+++ b/java/java-indexing-impl/src/com/intellij/compiler/CompilerReferenceService.java
@@ -26,6 +26,12 @@ import com.intellij.psi.search.GlobalSearchScope;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * The service is intended to provide an information about class/method/field usages or classes hierarchy that is obtained on compilation time.
+ * It means that this service should not affect any find usages result when initial project is not compiled or project language is not support
+ * by {@link LanguageLightRefAdapter} extension. Any result provided by this service should be valid even if some part of a given project was
+ * modified after compilation.
+ */
 public abstract class CompilerReferenceService extends AbstractProjectComponent {
   public static final RegistryValue IS_ENABLED_KEY = Registry.get("compiler.ref.index");
 
@@ -37,15 +43,27 @@ public abstract class CompilerReferenceService extends AbstractProjectComponent
     return project.getComponent(CompilerReferenceService.class);
   }
 
+  /**
+   * @return a scope where given element has no references in code. This scope might be not a strict scope where element is not occurred.
+   */
   @Nullable
   public abstract GlobalSearchScope getScopeWithoutCodeReferences(@NotNull PsiElement element);
 
+  /**
+   * @return a hierarchy of direct inheritors built on compilation time.
+   * This hierarchy is restricted by searchFileType and searchScope.
+   */
   @Nullable
   public abstract CompilerDirectHierarchyInfo getDirectInheritors(@NotNull PsiNamedElement aClass,
                                                                   @NotNull GlobalSearchScope useScope,
                                                                   @NotNull GlobalSearchScope searchScope,
                                                                   @NotNull FileType searchFileType);
 
+
+  /**
+   * @return a stream of functional expressions that implement given functional interface.
+   * This hierarchy is restricted by searchFileType and searchScope.
+   */
   @Nullable
   public abstract CompilerDirectHierarchyInfo getFunExpressions(@NotNull PsiNamedElement functionalInterface,
                                                                 @NotNull GlobalSearchScope useScope,