Docs: introduce some basic docs and contribution guides for Analysis API
diff --git a/docs/analysis-api/analysis-api-fe10.md b/docs/analysis-api/analysis-api-fe10.md
new file mode 100644
index 0000000..947c231
--- /dev/null
+++ b/docs/analysis-api/analysis-api-fe10.md
@@ -0,0 +1,2 @@
+# Analysis API FE1.0 Implementation
+TODO
\ No newline at end of file
diff --git a/docs/analysis-api/analysis-api-fir.md b/docs/analysis-api/analysis-api-fir.md
new file mode 100644
index 0000000..a052423
--- /dev/null
+++ b/docs/analysis-api/analysis-api-fir.md
@@ -0,0 +1,4 @@
+# Analysis API FIR Implementation
+To work with FIR compiler, FIR Analysis API Implementation uses [Low-Level API](low-level-api-fir.md)
+
+TODO
\ No newline at end of file
diff --git a/docs/analysis-api/analysis-api.md b/docs/analysis-api/analysis-api.md
new file mode 100644
index 0000000..0048ee0
--- /dev/null
+++ b/docs/analysis-api/analysis-api.md
@@ -0,0 +1,99 @@
+# Analysis API
+
+> Note: Analysis API is currently under active development and does not provide any compatibility guaranties.
+
+Analysis API is an API which allows analysing Kotlin code and retrieve compiler-related information. This includes:
+expression types, symbols, smartcast, and many others. Analysis API is an API which is used to implement Kotlin Plugin 2.0 which is under
+active development now too.
+
+Analysis API is frontend-independent. That means that it do not expose any Kotlin compiler internals.
+
+Analysis API itself is a just set of interfaces/abstraact classes without specific implementation inside. But there are two implementations
+currently available.
+
+* FIR-based implementation. FIR is a new compiler frontend which is a part of K2 Kotlin compiler. Read more:
+ * [Analysis API FIR Implementation documentation](analysis-api-fir.md)
+ * [Analysis API FIR Implementation source code](../../analysis/analysis-api-fir)
+ * [FIR Compiler documentation](../fir/fir-basics.md)
+* FE1.0-based implementation. FE1.0 is an original Kotlin compiler frontend. Read more:
+ * [Analysis API FE1.0 Implementation documentation](analysis-api-fe10.md)
+ * [Analysis API FE1.0 Implementation source code](../../analysis/analysis-api-fe10)
+
+Analysis API can work outside IntelliJ IDEA (e.g, it can be used for implementing Kotlin LSP server) but it still uses some basic classes
+form IntelliJ Core. This is needed mostly for working with [PsiElements](https://plugins.jetbrains.com/docs/intellij/psi-elements.html),
+lexical and syntax analysis.
+
+## KtAnalysisSession
+
+`KtAnalysisSession` is a view to the project modules and libraries from some fixed module, so called use-site module. From
+analysis `KtAnalysisSession` we can see only modules and libraries which are transitive dependencies of the use-site module.
+`KtAnalysisSession` contains set of functions to interact with **Analysis API** and it is the only way to interact with it.
+
+`KtAnalysisSession` has the following contracts:
+
+* **Lifecycle Owners** created in **KtAnalysisSession Scope** should not be leaked outside that scope
+* `KtAnalysisSession` receiver parameter should not be written to a variable or used as a function parameter. For decomposing analysis code
+ which should happen in **KtAnalysisSession Scope** consider passing `KtAnalysisSession` as function receiver parameter.
+* If function accept * **Lifecycle Owner** as parameter, it should always have `KtAnalysisSession` extension
+ receiver: `fun KtAnalysisSession.doSmthWithSymbol(symbol: KtSymbol) {...}`
+
+## KtAnalysisSession Scope
+
+All interaction with the Analysis API should be performed **only** in **KtAnalysisSession Scope**. To enter such scope `analyse`
+function should be used:
+
+```kotlin
+fun <R> analyze(contextElement: KtElement, action: KtAnalysisSession.() -> R): R
+```
+
+Where `action` lambda represents the **KtAnalysisSession Scope**.
+
+## Lifecycle Owners
+
+Every Lifecycle Owner has its lifecycle which is defined by corresponding `ValidityToken`. There is a special
+function `analyseWithCustomToken` which allows specifying needed behaviour. There are also analyse function which is made for the IDE which
+analyses with `ReadActionConfinementValidityToken`
+
+`ReadActionConfinementValidityToken` has the following contracts:
+
+* Accessibility contracts
+ * Analysis should not be called from **EDT Thread**
+ * If you have no choice consider using `analyseInModalWindow` function instead (but it may be rather slow and also shows a modal
+ window, so use it with caution)
+ * Analysis should be called from a **read action**
+ * Analysis should not be called outside **KtAnalysisSession Scope** (i.e, outside `analyse(context) { ... }` lambda
+* Validity contracts:
+ * Lifecycle Owner is valid only inside Analysis Context it was created in.
+
+## KtSymbol
+
+`KtSymbol`is an **Lifecycle Owner** that describes Kotlin or Java (as Kotlin sees it) declaration. `KtSymbol`represents:
+
+* Source Kotlin/Java declarations
+* Decompiled Kotlin/Java declarations
+* Synthetic Kotlin declarations (e.g, copy method of data class)
+
+Consider you want to take a symbol you got in one **KtAnalysisSession Scope** and use in another. It cannot be done directly as `KtSymbol`
+can not be leaked outside **KtAnalysisSession Scope**. But there is such thing as `
+KtSymbolPointer`. For every `KtSymbol`corresponding `KtSymbolPointer` can be created in one analysis session and symbol can be restored by
+using it in another. If between creating a symbol and restoring it, corresponding declaration changed then the symbol will not be restored
+and `KtSymbolPointer.restore` call will return the null value.
+
+## KtType
+
+`KtType` is an **Lifecycle Owner** that represents a Kotlin type in compiler-independent way.
+
+## KtScope
+
+The **Lifecycle Owner** which can answer the following queries:
+
+* What callable (functions and properties) symbols does this scope contains
+* What classifier (classes, type aliases, and type parameters) symbols does this scope contains
+
+For now the following scopes available:
+
+* **KtMemberScope** — contains members of the class with all members from super types,
+* **KtDeclaredMemberScope** — contains members of class which are directly declared in the class,
+* **KtPackageMemberScope** — contains all top-level declarations contained in the package,
+* **KtTypeScope** — contains all members which can be called on expression of some type.
+
diff --git a/docs/analysis-api/development-process/code-style.md b/docs/analysis-api/development-process/code-style.md
new file mode 100644
index 0000000..ed76437
--- /dev/null
+++ b/docs/analysis-api/development-process/code-style.md
@@ -0,0 +1,11 @@
+# Analysis API Code Style
+
+This is a code style for Analysis API modules which are located in [analysis directory](../../../analysis)
+
+* Please, follow [official Kotlin code style](https://kotlinlang.org/docs/coding-conventions.html).
+* IntelliJ IDEA is set up for these coding guidelines and the default formatter will help you a lot.
+* Consider using introducing explicit lambda parameter instead of implicit `it` parameter when:
+ * The lambda is multi-line, so includes multiple statements
+ * The `it` parameter is used multiple times inside lambda
+* Do not overuse `let`, `also`, `apply` and similar functions.
+ It seems cool to write a complex multiline function as a single expression but please, do not sacrifice code readability because of that.
diff --git a/docs/analysis-api/development-process/contributing-guidelines.md b/docs/analysis-api/development-process/contributing-guidelines.md
new file mode 100644
index 0000000..3675c52
--- /dev/null
+++ b/docs/analysis-api/development-process/contributing-guidelines.md
@@ -0,0 +1,196 @@
+# Contribution Guidelines
+
+This document is a contribution guideline for the development of **Analysis API** project. Please, follow it for your changes to be
+accepted.
+
+## General Guidelines
+
+* Follow the [Code Style](code-style.md)
+* Write new code in **Kotlin**. It is totally okay to write Java code in existing Java files. You can always use **Java To Kotlin
+ Converter** to convert it to Kotlin.
+* Always write **Unit Tests** for your changes.
+* Always perform **code formatting** and call **import optimizer** before committing your changes.
+* Do not use short names in declarations names
+ * Bad: `val dclSmbl: KtDeclarationSymbol`
+ * Good `val declarationSymbol: KtDeclarationSymbol`
+
+## Always add KDoc to any public declaration inside [analysis-api](../../../analysis/analysis-api) module
+
+This includes:
+
+* Public classes;
+* Public class members (functions/properties);
+* Class constructor parameters which are declared as public class members via `val`/`var`;
+* Top-level functions/properties.
+
+Do not hesitate to make the KDoc as long and **detailed** as possible until the information you write will help others to use your API
+changes in a better way.
+
+### A good KDoc should include
+
+#### What this declaration is about?
+
+Please do not include obvious KDocs, which do not add additional information. Always describe the purpose of the declaration.
+
+Bad (adds no information to the declaration name):
+
+```kotlin
+public class KtAnnotationApplication(
+ /**
+ * ClassId of annotation
+ */
+ val classId: ClassId
+)
+```
+
+Good:
+
+```kotlin
+public class KtAnnotationApplication(
+ /**
+ * A fully qualified name of annotation class which is being applied.
+ */
+ val classId: ClassId
+)
+```
+
+#### Explanation of corner cases and examples
+
+Please, explain (better with examples) how the new functionality you add behaves on corner cases.
+
+Example:
+
+```kotlin
+/**
+ * Get type of given expression.
+ *
+ * Return:
+ * - [KtExpression] type if given [KtExpression] is real expression;
+ * - `null` for [KtExpression] inside packages and import declarations;
+ * - `Unit` type for statements;
+ */
+public fun KtExpression.getKtType(): KtType?
+```
+
+## Keep Analysis API Surface Area Concise and Minimal
+
+As you already know, Analysis API is a compiler API used to retrieve compiler-related information for FIR IDE Plugin. It is used in a wide
+range of features: code completion, debugger, inspections, and all other features which require compiler-related information. So it is
+important to keep the Analysis API Surface Area concise. Whether you want to introduce a new method or change the behavior of the existing
+method, consider
+
+* Will your change be useful for others?
+* Will it be possible to implement your task without modifying Analysis API? If yes, maybe it would be a better solution to just implement
+ the functionality you need as some utility function on your project side.
+
+## Always write Unit Tests for your code
+
+It was already mentioned in the general part of the guidelines but Unit Tests are an important thing for public API. So, write **Unit Test**
+whenever you add new functionality or modify existing behavior (either fixing bug or adding feature). A good unit test:
+
+* Should cover basic usage scenarios
+* Should cover corner-cases
+
+If you fixed a bug or added new functionality to an existing feature, consider adding test(s) which cover it.
+
+## Follow Naming Conventions
+
+* All public declarations which are exposed to the surface area of Analysis API should have `Kt` prefix. E.g, `KtSymbol`, `KtConstantValue`.
+
+## Follow Analysis API Implementation Contracts
+
+* Add `ValidityTokenOwner` as supertype for all declarations which contains other `ValidityTokenOwner` inside (eg, via parameter types,
+ function return types) to ensure that internal `ValidityTokenOwner` are not exposed via your declaration.
+* You have some declaration which implements `ValidityTokenOwner`. It means that this declaration has a lifetime. And this declaration has
+ to be checked to ensure that it is not used after its lifetime has come to the end. To ensure that all methods(except `hashCode`/`equals`
+ /`toString`) and properties should be wrapped into `withValidityAssertion { .. }` check:
+
+```kotlin
+public class KtCall(
+ private val _symbol: KtSymbol,
+ private val _isInvokeCall: Boolean,
+) : ValidityTokenOwner {
+ public val symbol: KtSymbol get() = withValidityAssertion { _symbol }
+ public val isInvokeCall: Boolean get() = withValidityAssertion { _isInvokeCall }
+
+ public fun isImplicitCall(): Boolean = withValidityAssertion {
+ // IMPL
+ }
+
+ override fun equals(other: Any?): Boolean { // no withValidityAssertion
+ // IMPL
+ }
+ override fun hashCode(): Int { // no withValidityAssertion
+ // IMPL
+ }
+ override fun toString(): String { // no withValidityAssertion
+ // IMPL
+ }
+}
+```
+
+## Keep your classes and functions with the lowest possible visibility
+
+The only part of Analysis API which should be exposed is the Analysis API surface area (the API itself). All other declarations should be
+kept `internal` or `private`. To ensure that, [analysis-api module](../../../analysis/analysis-api)
+has [Library Mode](https://github.com/Kotlin/KEEP/blob/master/proposals/explicit-api-mode.md) enabled. This will enforce that only
+declarations which are supposed to be exposed are really exposed. There are no guarantees on the non-surface part of analysis API on binary
+and source compatibility.
+
+Also, the implementation modules should be considered as internal themselves. Please, keep declarations there `internal` or `private` too
+then it is possible. Implementation modules are:
+
+* [Analysis API FIR Implementation](../../../analysis/analysis-api-fir)
+* [Analysis API FE1.0 Implementation](../../../analysis/analysis-api-fe10)
+
+## Properly design utility functions
+
+In compiler-related code (and Analysis API is compiler-related 😀), there may be a lot of Kotlin top-level utility functions and properties
+to work with AST, `PsiElements`, and others. Such code pollutes public and internal namespaces and introduces a lot of functions with
+unclear semantics:
+
+* If you have a utility function that uses one or more private functions and those functions are used only by it, consider encapsulating the
+ whole functions family into a class or object.
+
+Bad:
+
+```kotlin
+internal fun render(value: KtAnnotationValue): String = buildString { renderConstantValue(value) }
+
+private fun StringBuilder.renderConstantValue(value: KtAnnotationValue) {
+ when (value) {
+ is KtAnnotationApplicationValue -> renderAnnotationConstantValue(value)
+ ...
+ }
+}
+
+private fun StringBuilder.renderConstantAnnotationValue(value: KtConstantAnnotationValue) {
+ append(value.constantValue.renderAsKotlinConstant())
+}
+
+// A lot of other non-related utility functions in the same file
+```
+
+Good:
+
+```kotlin
+internal object KtAnnotationRenderer {
+ fun render(value: KtAnnotationValue): String = buildString { renderConstantValue(value) }
+
+ private fun StringBuilder.renderConstantValue(value: KtAnnotationValue) {
+ when (value) {
+ is KtAnnotationApplicationValue -> renderAnnotationConstantValue(value)
+ ...
+ }
+ }
+
+ private fun StringBuilder.renderConstantAnnotationValue(value: KtConstantAnnotationValue) {
+ append(value.constantValue.renderAsKotlinConstant())
+ }
+}
+```
+
+* Your utility function may be useful for others or maybe very specific for your task. Please, decide if you want others to reuse your code
+ or not. If not, and it is very task-specific, consider hiding it in your implementation. Otherwise, feel free to introduce it as a
+ top-level function/object. For the latter case, it would be good to have a KDoc for it :)
+
diff --git a/docs/analysis-api/development-process/development-process.md b/docs/analysis-api/development-process/development-process.md
new file mode 100644
index 0000000..d2e21f3
--- /dev/null
+++ b/docs/analysis-api/development-process/development-process.md
@@ -0,0 +1,4 @@
+# Analysis API Development Process
+
+* Analysis API is under active development now, and it is completely OK to make big and heavy changes. The main client of Analysis API now is FIR IDE. Please, make corresponding changes to the FIR IDE code on changes inside Analysis API. (TODO links to coop dev setup)
+* Please read [Contributing Guidelines](contributing-guidelines.md) and [Code Style](code-style.md) requirements before start working on Analysis API.
diff --git a/docs/analysis-api/low-level-api-fir.md b/docs/analysis-api/low-level-api-fir.md
new file mode 100644
index 0000000..a077bf6
--- /dev/null
+++ b/docs/analysis-api/low-level-api-fir.md
@@ -0,0 +1,71 @@
+# Low Level API
+
+Low-level API (LL API) is an interlayer between Analysis API FIR Implementation and FIR compiler. Low-level API is responsible for:
+
+* Finding corresponding `FirElement` by `KtElement`
+* Lazy resolving of `FirDeclaration`
+* Collecting diagnostics for `FirDeclaration`
+* Incremental code analysis
+* Implementing FIR providers using IJ indexes
+
+You can read about how FIR compiler works [here](../fir/fir-basics.md)
+
+The entry point for LL API is `FirModuleResolveState`.` FirModuleResolveState` is a view of project modules visible from the current module.
+The lifetime of
+`FirModuleResolveState` is limited by Kotlin Out of Block Modification.
+
+## Mapping KtElement to FirElement (KT -> FIR) & Incremental Analysis
+
+To implement some stuff in Analysis API, we need to get resolved `FirElement` by the given `KtElement`. Also, this functionality is
+considered to be used not very often (mostly, for the files opened in the editor) as it resolves some declarations to the `BODY_RESOLVE` and
+collects `KT -> FIR` mappings for it.
+
+Finding `KT -> FIR` mappings works like the following:
+
+* For every `KtFile` we need mapping for, we have `FileStructure` which contains a tree like-structure of `FileStructureElement`
+* `FileStructureElement` can be one of the following:
+ * `ReanalyzableStructureElement` represents a non-local declaration that can be incrementally reanalyzed after non-out of block change
+ inside it.
+ * `NonReanalyzableDeclarationStructureElement` represents non-local declaration which can not be incrementally reanalyzed
+ * `RootFileStructureElement` represents file except all declarations inside
+* `FileStructureElement` form a nested tree-like structure
+* Then we want to get `KT -> FIR` mapping we find containing `FileStructureElement`. If is not up-to-date we rebuild it and then take from
+ it.
+
+The following declarations can be reanalyzed (in other words, can be represented as ReanalyzableStructureElement):
+
+* Functions with explicit return type
+* Properties with explicit type
+* Secondary constructors
+* Getters/setters of the property with explicit type
+
+# Lazy Declaration resolving
+
+FIR in compiler mode works by sequentially running every resolve phase on all files at once like shown in pseudo-code:
+
+```kotlin
+for (phase in allResolvePhases) {
+ for (file in allFirFiles) {
+ runPhaseOnFile(file, phase)
+ }
+}
+```
+
+Such behavior does not work for the Analysis API. Analysis API needs to resolve one specific declaration to the minimum possible phase. To
+solve that problem, there are *lazy phases*. Lazy phases can be run only on a single declaration, not on the whole `FirFile`.
+
+Suppose we need to resolve some `FirDeclaration` to phase number `N`:
+
+* First, we resolve the whole containing `FirFile` to the `IMPORTS` phase,
+* Then we resolve file annotations,
+* When we find a non-local container for our declaration as only non-local declarations can be lazily resolved for now,
+* Finally, resolve *only* that container from phase number `1` to phase `N`
+
+All resolve happens under containing file-based *write lock*.
+
+## Project Module Structure
+
+The `FirModuleResolveState` represents a view from a specific module (**root module**) to the dependent modules. A module is represented by:
+
+* `FirIdeSourcesSession` the implementation of `FirSession` (FIR compiler representation of a module)
+* `ModuleFileCache` the `KtFile -> FirFile` cache & also caches for FIR providers
\ No newline at end of file
