[AA] Edit documentation of analyze and related classes

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/KtAnalysisSession.kt

@@ -17,16 +17,18 @@ import org.jetbrains.kotlin.psi.KtElement
 import org.jetbrains.kotlin.psi.KtFile
 
 /**
- * The entry point into all frontend-related work. Has the following contracts:
+ * [KtAnalysisSession] is the entry point into all frontend-related work. It has the following contracts:
- * - Should not be accessed from event dispatch thread
- * - Should not be accessed outside read action
- * - Should not be leaked outside read action it was created in
- * - To be sure that session is not leaked it is forbidden to store it in a variable, consider working with it only in [analyse] context
- * - All entities retrieved from analysis session should not be leaked outside the read action KtAnalysisSession was created in
  *
- * To pass a symbol from one read action to another use [KtSymbolPointer] which can be created from a symbol by [KtSymbol.createPointer]
+ * - It should not be accessed from event dispatch thread.
+ * - It should not be accessed outside a read action.
+ * - It should not be leaked outside the read action it was created in.
+ * - To be sure that an analysis session is not leaked, it is forbidden to store it in a variable. Consider working with it only inside
+ *   [analyze] blocks, and pass it to functions via context receivers (e.g. `context(KtAnalysisSession)`).
+ * - All entities retrieved from an analysis session should not be leaked outside the read action the analysis session was created in.
  *
- * To create analysis session consider using [analyse]
+ * To pass a symbol from one read action to another use [KtSymbolPointer], which can be created from a symbol by [KtSymbol.createPointer].
+ *
+ * To create a [KtAnalysisSession], please use [analyze] or one of its siblings.
  */
 @OptIn(KtAnalysisApiInternals::class)
 @Suppress("AnalysisApiMissingLifetimeCheck")

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt

@@ -7,15 +7,16 @@
 
 package org.jetbrains.kotlin.analysis.api
 
+import org.jetbrains.kotlin.analysis.api.lifetime.KtLifetimeTokenFactory
 import org.jetbrains.kotlin.analysis.api.session.KtAnalysisSessionProvider
 import org.jetbrains.kotlin.analysis.project.structure.KtModule
 import org.jetbrains.kotlin.psi.KtElement
 import org.jetbrains.kotlin.psi.KtFile
 
 /**
- * Execute given [action] in [KtAnalysisSession] context
+ * Executes the given [action] in a [KtAnalysisSession] context.
- * Uses [useSiteKtElement] as an [KtElement] which containing module is a use-site module,
+ *
- * i.e, the module from which perspective the project will be analyzed.
+ * The project will be analyzed from the perspective of [useSiteKtElement]'s module, also called the use-site module.
  *
  * @see KtAnalysisSession
  */
@@ -26,10 +27,10 @@ public inline fun <R> analyze(
     KtAnalysisSessionProvider.getInstance(useSiteKtElement.project)
         .analyse(useSiteKtElement, action)
 
-
 /**
- * Execute given [action] in [KtAnalysisSession] context
+ * Executes the given [action] in a [KtAnalysisSession] context.
- * Uses [useSiteKtModule] as use-site module, i.e, the module from which perspective the project will be analyzed.
+ *
+ * The project will be analyzed from the perspective of the given [useSiteKtModule].
  *
  * @see KtAnalysisSession
  * @see KtLifetimeTokenFactory

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/session/KtAnalysisSessionProvider.kt

@@ -18,8 +18,10 @@ import org.jetbrains.kotlin.psi.KtElement
 import org.jetbrains.kotlin.psi.KtFile
 
 /**
- * Provides [KtAnalysisSession] by [contextElement]
+ * Provides [KtAnalysisSession]s by use-site [KtElement]s or [KtModule]s.
- * Should not be used directly, consider using [analyse]/[analyzeWithReadAction]/[analyzeInModalWindow] instead
+ *
+ * This provider should not be used directly. Please use [analyze][org.jetbrains.kotlin.analysis.api.analyze] or
+ * [analyzeInDependedAnalysisSession][org.jetbrains.kotlin.analysis.api.analyzeInDependedAnalysisSession] instead.
  */
 @OptIn(KtAnalysisApiInternals::class)
 public abstract class KtAnalysisSessionProvider(public val project: Project) : Disposable {