From d38e7973994d3f48db20c69918e07aabc1de5a0a Mon Sep 17 00:00:00 2001
From: Ilya Kirillov <ilya.kirillov@jetbrains.com>
Date: Fri, 28 Jan 2022 17:59:25 +0100
Subject: [PATCH] Docs: Analysis API Usage document

---
 .../analysis-api/analysis-api-usage.md        | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 docs/analysis/analysis-api/analysis-api-usage.md

diff --git a/docs/analysis/analysis-api/analysis-api-usage.md b/docs/analysis/analysis-api/analysis-api-usage.md
new file mode 100644
index 00000000000..1b9f5fbd541
--- /dev/null
+++ b/docs/analysis/analysis-api/analysis-api-usage.md
@@ -0,0 +1,25 @@
+# Analysis API Usage
+
+To use Analysis API, you need to be in the `KtAnalysisSessoin` context. Basically, it means that you need to call [`analyse(contextElement: KtElement, action: KtAnalysisSession.() -> R): R`](https://github.com/JetBrains/kotlin/blob/master/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/KtAnalysisSessionProvider.kt#L106) function. All your actions with Analysis API will be performed with `KtAnalysisSessoin` receiver available.
+```kotlin
+analyse(psiElementForContext) { // you are inside KtAnalysisSession Context
+    // you can use a wide variety of Analysis API functions here: work with types, symbols, signatures, scopes and more.
+}
+```
+## Functions
+You may want to decompose your logic into functions. In such a case, add KtAnalysisSession receiver to it. Such a thing should be done even if your function does not use the receiver. The approach may look cumbersome, but it is important to be sure that we do not publish resolution results. Publishing resolution results may cause memory leaks or working with out-of-date resolution results.
+```kotlin
+analyse(psiElementForContext) {
+    val symbol = getSymbol()
+    ...
+}
+
+fun KtAnalysisSession.getSymbol() : KtSymbol {
+    // the body of this function is also inside KtAnalysisSession context and may use it 
+}
+```
+
+## No leakages of ValidityTokenOwners from KtAnalysisSession context
+All `ValidityTokenOwners` you get inside a `KtAnalysisSessoin` context should never leak it. But you may:
+* Store your `ValidityTokenOwners` as a field inside a class that implements `ValidityTokenOwners`. This way your outer class is `ValidityTokenOwners` itself and all rules apply to it. 
+* Pass it to another function with a `KtAnalysisSessoin` receiver.
\ No newline at end of file