Analysis API: add KDoc to providers

analysis/analysis-api-providers/src/org/jetbrains/kotlin/analysis/providers/KotlinDeclarationProvider.kt

@@ -14,6 +14,10 @@ import org.jetbrains.kotlin.name.FqName
 import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.psi.*
 
+/**
+ * A declaration provider for a given scope. Can be created via [KotlinDeclarationProviderFactory].
+ * May be called frequently, so for implementations it is better to cache results.
+ */
 public abstract class KotlinDeclarationProvider {
     public abstract fun getClassesByClassId(classId: ClassId): Collection<KtClassOrObject>
     public abstract fun getTypeAliasesByClassId(classId: ClassId): Collection<KtTypeAlias>

analysis/analysis-api-providers/src/org/jetbrains/kotlin/analysis/providers/KotlinModificationTrackerFactory.kt

@@ -11,24 +11,89 @@ import com.intellij.openapi.util.ModificationTracker
 import org.jetbrains.annotations.TestOnly
 import org.jetbrains.kotlin.analysis.project.structure.KtSourceModule
 
+
 public abstract class KotlinModificationTrackerFactory {
+    /**
+     * Creates **OOBM** tracker which is incremented every time there is **OOB** change in some source project module.
+     *
+     * See [createModuleWithoutDependenciesOutOfBlockModificationTracker] for the definition of **OOBM**.
+     * @see ModificationTracker
+     */
     public abstract fun createProjectWideOutOfBlockModificationTracker(): ModificationTracker
+
+    /**
+     * Creates **OOBM** tracker which is incremented every time there is OOB change in the [module].
+     * This tracker should not consider changes in dependent modules.
+     * If you do not need incrementalliy in your tool (eg, it is okay to reanalyse the whole worked on every source code change) consider incrementing returned tracker on every source code change.
+     * If tour tool works with static code (so no codebase changes in possible) just return static modification tracker here.
+     *
+     * **Out Of Block Modification (OOBM)** is a such modification in source code which may change resolve of other non-local declarations.
+     *
+     * Consider the following example #1:
+     * ```
+     * val x = 10<caret>
+     * val z = x
+     * ```
+     * If we change initializer of `x` to `"str"` the return type of `x` will become 'String' instead of initial `Int`.
+     * This will change the return type of `z` as it does not have explicit type specified. So, it is an **OOBM**.
+     *
+     *
+     * Consider example #2:
+     *  ```
+     * val x: Int = 10<caret>
+     * val z = x
+     * ```
+     * If we change 10 to "str" as in example #1, it would not change type of z, so it is not **OOBM**.
+     *
+     * Example of modifications in source code, which results **OOBM**
+     * - modification inside non-local (ie, accessible outside) declaration without explicit return type specified
+     * - modification o a package
+     * - creating new declaration
+     * - moving declaration to another package
+     *
+     * Generally, all modifications which happens outside callable declaration (function, accessor or property) body with explicit type are considered **OOBM**
+     * @see ModificationTracker
+     */
     public abstract fun createModuleWithoutDependenciesOutOfBlockModificationTracker(module: KtSourceModule): ModificationTracker
+
+    /**
+     * Creates modification tracker which is incremented every time libraries in project are changed.
+     *
+     * See [KotlinModificationTrackerFactory] for the definition of **OOBM**.
+     * @see ModificationTracker
+     */
     public abstract fun createLibrariesModificationTracker(): ModificationTracker
 
     @TestOnly
     public abstract fun incrementModificationsCount()
 }
 
+/**
+ * Creates **OOBM** tracker which is incremented every time there is OOB change in some source project module.
+ *
+ * See [KotlinModificationTrackerFactory.createModuleWithoutDependenciesOutOfBlockModificationTracker] for the definition of **OOBM**.
+ * @see ModificationTracker
+ */
 public fun Project.createProjectWideOutOfBlockModificationTracker(): ModificationTracker =
     ServiceManager.getService(this, KotlinModificationTrackerFactory::class.java)
         .createProjectWideOutOfBlockModificationTracker()
 
+/**
+ * Creates **OOBM** tracker which is incremented every time there is OOB change in the [module].
+ *
+ * See [KotlinModificationTrackerFactory.createModuleWithoutDependenciesOutOfBlockModificationTracker] for the definition of **OOBM**.
+ * @see ModificationTracker
+ */
+public fun KtSourceModule.createModuleWithoutDependenciesOutOfBlockModificationTracker(project: Project): ModificationTracker =
+    ServiceManager.getService(project, KotlinModificationTrackerFactory::class.java)
+        .createModuleWithoutDependenciesOutOfBlockModificationTracker(this)
+
+/**
+ * Creates modification tracker which is incremented every time libraries in project are changed.
+ *
+ * See [KotlinModificationTrackerFactory] for the definition of **OOBM**.
+ * @see ModificationTracker
+ */
 public fun Project.createLibrariesModificationTracker(): ModificationTracker =
     ServiceManager.getService(this, KotlinModificationTrackerFactory::class.java)
         .createLibrariesModificationTracker()
-
-
-public fun KtSourceModule.createModuleWithoutDependenciesOutOfBlockModificationTracker(project: Project): ModificationTracker =
-    ServiceManager.getService(project, KotlinModificationTrackerFactory::class.java)
-        .createModuleWithoutDependenciesOutOfBlockModificationTracker(this)

analysis/analysis-api-providers/src/org/jetbrains/kotlin/analysis/providers/KotlinPackageProvider.kt

@@ -11,7 +11,16 @@ import com.intellij.psi.search.GlobalSearchScope
 import org.jetbrains.kotlin.name.FqName
 import org.jetbrains.kotlin.name.Name
 
+/**
+ * Provides information about Kotlin packages in the given scope. Can be constructed via [KotlinPackageProviderFactory]
+ * [doKotlinPackageExists] is called very often by a FIR compiler. And implementations should consider cache results.
+ */
 public abstract class KotlinPackageProvider {
+    /**
+     * Checks if a package with given [FqName] exists in current [GlobalSearchScope].
+     * Note, that for Kotlin it is not mandatory for a package to correspond to a directory structure like in Java.
+     * So, a package [FqName] is determined by Kotlin files package directive.
+     */
     public abstract fun doKotlinPackageExists(packageFqName: FqName): Boolean
     public abstract fun getKotlinSubPackageFqNames(packageFqName: FqName): Set<Name>
 }