Proofread the documentation

Author: yanex

README.md

@@ -8,6 +8,6 @@ You might want to check the [generated documentation website](https://kotl.in/an
 
 ---
 
-Analysis API is a powerful library for analyzing code in Kotlin.
+The Analysis API is a powerful library for analyzing code in Kotlin.
 Made on top of the Kotlin PSI syntax tree, it provides access to various semantic information, including reference targets,
 expression types, declaration scopes, diagnostics, and more.

Writerside/topics/Annotations.md

@@ -1,7 +1,7 @@
 # Annotations
 
-Annotations play a crucial role in Kotlin, providing metadata and influencing code behavior. Analysis API allows you
-to access and analyze annotations applied to both declarations and types.
+Annotations play a crucial role in Kotlin, providing metadata and influencing code behavior.
+The Analysis API allows you to access and analyze annotations applied to both declarations and types.
 
 ## KaAnnotated
 

Writerside/topics/Diagnostics.md

@@ -1,7 +1,7 @@
 # Diagnostics
 
-Analysis API allows you to access and analyze compiler diagnostics (errors and warnings) associated with entire files
-or specific elements.
+The Analysis API allows you to access and analyze compiler diagnostics (errors and warnings) associated with entire
+files or specific elements.
 
 ## Diagnostics in a `KtFile`
 
@@ -41,8 +41,6 @@ Note that the returned list of diagnostics does not include diagnostics for nest
 `collectDiagnostics` and `diagnostics` return a collection of `KtDiagnosticWithPsi` instances.
 This interface provides access to information about the diagnostic.
 
-
-
 | Member           | Description                                                                   |
 |------------------|-------------------------------------------------------------------------------|
 | `severity`       | The severity of the diagnostic (e.g., `ERROR`, `WARNING`).                    |

Writerside/topics/File-Compilation.md

@@ -2,8 +2,8 @@
 
 <note>Experimental API. Subject to changes.</note>
 
-Analysis API enables in-memory compilation of Kotlin files. This allows your tools and plugins to generate and compile
-Kotlin code without writing files to disk or invoking the command-line compiler.
+The Analysis API enables in-memory compilation of Kotlin files. This allows your tools and plugins to generate and
+compile Kotlin code without writing files to disk or invoking the command-line compiler.
 
 ## Usage
 

Writerside/topics/Fundamentals.md

@@ -4,12 +4,12 @@ This page covers a few fundamental concepts and rules of the Analysis API. Pleas
 
 ## Kotlin PSI
 
-The Kotlin compiler exposes a Kotlin abstract syntax tree, made on top of the
-[PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) API, a part of IntelliJ IDEA. For some languages, such as
-Java, the PSI acts both as a syntax tree, and as a source of semantic information. In Kotlin, though, these concepts
+The Kotlin compiler exposes a Kotlin abstract syntax tree, built on top of
+the [PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) API, a part of IntelliJ IDEA. For some languages, such
+as Java, the PSI acts both as a syntax tree and as a source of semantic information. In Kotlin, though, these concepts
 are clearly separated.
 
-Below there is a simplified tree of the Kotlin PSI hierarchy.
+Below is a simplified tree of the Kotlin PSI hierarchy.
 
 <code-block lang="mermaid">
 graph TD
@@ -28,24 +28,25 @@ graph TD
   KtExpression --> KtBlockExpression
 </code-block>
 
-`KtElement` is a root type of the hierarchy. `KtDeclaration` and `KtExpression` are two notable subtypes of it.
-`KtDeclaration` itself is an expression – so makes it possible to have local classes and functions.
+`KtElement` is the root type of the hierarchy. `KtDeclaration` and `KtExpression` are two notable subtypes of
+it. `KtDeclaration` itself is an expression, which makes it possible to have local classes and functions.
 
-The Kotlin PSI does not have a strict separation between statements and expressions. There is, however, a
-`KtStatementExpression` marker interface that annotates statement-like constructs.
+The Kotlin PSI does not have a strict separation between statements and expressions. There is, however,
+a `KtStatementExpression` marker interface that annotates statement-like constructs.
 
-Analysis API is implemented on top of the Kotlin PSI, mostly as a set of extension functions and properties, providing
-access to semantic information. Such as, to get an expression type, there is a `ktExpression.expressionType` extension
-property. Or, to get a resolved call information, one should use `ktCallExpression.resolveToCall()`.
+The Analysis API is implemented on top of the Kotlin PSI, mostly as a set of extension functions and properties,
+providing access to semantic information. For example, to get an expression type, there is
+a `ktExpression.expressionType` extension property. Or, to get resolved call information, one should
+use `ktCallExpression.resolveToCall()`.
 
 ## KaSession
 
-`KaSession` is the entry point for interacting with Analysis API. It provides access to various components and utilities
-needed for analyzing code in Kotlin.
+`KaSession` is the entry point for interacting with the Analysis API. It provides access to various components and
+utilities needed for analyzing code in Kotlin.
 
-Each `KaSession` is associated with some specific module and provides analysis results from the perspective of that
-module. In other words, a `KaSession` only sees declarations from the owning (use-site) module, and from all
-dependencies of it, both direct and transitive.
+Each `KaSession` is associated with a specific module and provides analysis results from the perspective of that module.
+In other words, a `KaSession` only sees declarations from the owning (use-site) module and from all its dependencies,
+both direct and transitive.
 
 To get a `KaSession`, use the `analyze {}` function, passing a `KtModule` or some `KtElement` from that module:
 
@@ -61,9 +62,9 @@ fun perform(element: KtElement) {
 The `KaSession` is available as an extension receiver within the lambda block. The session is valid only within this
 block, and it **should not** be stored or accessed outside of it.
 
-The `analyze {}` call is only available inside
-[read actions](https://plugins.jetbrains.com/docs/intellij/general-threading-rules.html#read-access). You can use the
-`@RequiresReadLock` annotation to specify that the method must be called from a read action. In latter parts of the
+The `analyze {}` call is only available
+inside [read actions](https://plugins.jetbrains.com/docs/intellij/general-threading-rules.html#read-access). You can use
+the `@RequiresReadLock` annotation to specify that the method must be called from a read action. In later parts of the
 documentation, the annotation is not added for clarity.
 
 ## KaLifetimeOwner
@@ -72,11 +73,11 @@ documentation, the annotation is not added for clarity.
 the `analyze` block in which they were created. All such entities have the `KaLifetimeOwner` supertype.
 
 It is crucial to avoid caching `KaLifetimeOwner`s for an arbitrary time, including storing them in properties of
-long-living classes, or in static context. Doing so will likely lead to severe memory leaks as these entities hold the
+long-living classes or in a static context. Doing so will likely lead to severe memory leaks as these entities hold the
 whole underlying resolution session. Always retrieve and use them within the `analyze` block or pass them as parameters
 to functions that require them.
 
-If you need to extract parts of resolution logic to a separate function, prefer passing the `KaSession` as an
+If you need to extract parts of the resolution logic to a separate function, prefer passing the `KaSession` as an
 extension or ordinary parameter, instead of keeping it in some shared context class.
 
 ```Kotlin
@@ -94,7 +95,7 @@ fun KaSession.check(element: KtElement) { ... }
 fun modify(element: KtElement) { ... }
 ```
 
-Inside the `analyze {} `block, `KaSession` is also available as a `useSiteSession` property:
+Inside the `analyze {}` block, `KaSession` is also available as a `useSiteSession` property:
 
 ```Kotlin
 fun perform(element: KtElement) {

Writerside/topics/Index.md

@@ -1,14 +1,14 @@
 # Analysis API
 
-Analysis API is a powerful library for analyzing code in Kotlin. Made on top of the Kotlin PSI syntax tree, it provides
-access to various semantic information, including reference targets, expression types, declaration scopes, diagnostics
-and more.
+The Analysis API is a powerful library for analyzing code in Kotlin. Built on top of the Kotlin PSI syntax tree,
+it provides access to various semantic information, including reference targets, expression types, declaration scopes,
+diagnostics, and more.
 
-While Analysis API uses the Kotlin compiler internally, the API layer itself does not expose any compiler internals.
+While the Analysis API uses the Kotlin compiler internally, the API layer itself does not expose any compiler internals.
 The library offers both source and binary backward compatibility for its stable parts.
 
-Analysis API encapsulates all challenging parts needed for efficient Kotlin code analysis, including lazy resolution and
-cache invalidation, so you can focus on the actual code handling logic.
+The Analysis API encapsulates all challenging parts needed for efficient Kotlin code analysis, including lazy resolution
+and cache invalidation, so you can focus on the actual code handling logic.
 
 ## Quick example
 
@@ -26,7 +26,7 @@ fun KtExpression.hasStringType(): Boolean {
 Most of the Analysis API surface can be accessed from inside `analyze {}` blocks. Such is the `expressionType` extension
 property – for the given `KtExpression`, it returns the resolved type.
 
-`builtinTypes` is also a part of Analysis API available inside the analysis block. It provides access to basic
+`builtinTypes` is also a part of the Analysis API available inside the analysis block. It provides access to basic
 Kotlin types, including number types, `Any`, `Nothing`, and `String`.
 
 The type of `builtinTypes.string` is a `KaType`. `Ka` is a common prefix for all Analysis API components and
@@ -35,20 +35,20 @@ Check the [KaLifetimeOwner](Fundamentals.md#kalifetimeowner) section for more in
 
 ## Using in IntelliJ IDEA
 
-Analysis API is not just some external API. It serves as the foundation for many features within the Kotlin plugin for
-IntelliJ IDEA, including code completion, navigation across declarations, refactorings, inspections, debugger, and
-many more. By using Analysis API, you get the same tools as the developers of the Kotlin plugin itself.
+The Analysis API is not just some external API. It serves as the foundation for many features within the Kotlin plugin
+for IntelliJ IDEA, including code completion, navigation across declarations, refactorings, inspections, the debugger,
+and many more. By using the Analysis API, you get the same tools as the developers of the Kotlin plugin itself.
 
-Analysis API mainly targets the K2 Kotlin compiler, but there is also limited support for the legacy 1.0 compiler.
-So the same piece of logic, if implemented on top of Analysis API, can work both in the K1 and K2 Kotlin modes.
+The Analysis API mainly targets the K2 Kotlin compiler, but there is also limited support for the legacy 1.0 compiler.
+So the same piece of logic, if implemented on top of the Analysis API, can work both in the K1 and K2 Kotlin modes.
 
 ## Using in command-line tools
 
-Analysis API can also be used in command-line tools that perform Kotlin code analysis, including linters, documentation
-generators, and code generating utilities.
+The Analysis API can also be used in command-line tools that perform Kotlin code analysis, including linters,
+documentation generators, and code-generating utilities.
 
 <note>
     Currently, the only officially supported use-case is IntelliJ IDEA plugin development.
-    While Analysis API provides the Standalone mode for command-line tool developers, it is currently in development
+    While the Analysis API provides the Standalone mode for command-line tool developers, it is currently in development
     and subject to incompatible changes.
 </note>

Writerside/topics/Java-Kotlin-Bridging.md

@@ -2,13 +2,13 @@
 
 <note>Experimental API. Subject to changes.</note>
 
-While Analysis API exposes declarations and types from the Kotlin standpoint, it works also with Java source and library
-declarations. The API provides a set of utilities for converting between Kotlin and Java views of declarations.
+While the Analysis API exposes declarations and types from the Kotlin standpoint, it works also with Java source and
+library declarations. The API provides a set of utilities for converting between Kotlin and Java views of declarations.
 
 ## Types
 
 In IntelliJ IDEA, `PsiType` is a representation for Java types. Conceptually, it is similar to [`KaType`](KaType.md).
-Analysis API provides mapping between the two representations.
+The Analysis API provides mapping between the two representations.
 
 `fun PsiType.asKaType(useSitePosition: PsiElement): KaType?`
 : Convert the given Java type to a `KaType`.
@@ -30,7 +30,7 @@ Analysis API provides mapping between the two representations.
 
 ## Symbols
 
-Analysis API can create symbols for Java declarations.
+The Analysis API can create symbols for Java declarations.
 
 `val PsiClass.namedClassSymbol: KaNamedClassSymbol?`
 : Map a Java class to a class symbol. Always `null` for anonymous classes and type parameters (that are also

Writerside/topics/KaAnonymousObjectSymbol.md

@@ -1,6 +1,6 @@
 # KaAnonymousObjectSymbol
 
-Represents anonymous object symbols, such as:
+Represents an anonymous object declaration, such as:
 
 ```Kotlin
 object : Runnable {

Writerside/topics/KaCall.md

@@ -1,7 +1,8 @@
 # KaCall
 
 Represents a call within Kotlin code. It encompasses various types of calls, including function calls, property
-accesses, and other invocations. Analysis API provides a hierarchy of `KtCall` subtypes to model different call kinds.
+accesses, and other invocations. The Analysis API provides a hierarchy of `KtCall` subtypes to model different call
+kinds.
 
 <code-block lang="mermaid">
 graph TB

Writerside/topics/KaCallableSymbol.md

@@ -7,15 +7,15 @@ A base class for symbols that represent callable declarations, such as functions
 A sealed class.  
 Inherits from [KaDeclarationSymbol](KaDeclarationSymbol.md).
 
-Notable inheritors: [KaFunctionSymbol](KaFunctionSymbol.md), [KaVariableSymbol](KaVariableSymbol.md). 
+Notable inheritors: [KaFunctionSymbol](KaFunctionSymbol.md), [KaVariableSymbol](KaVariableSymbol.md).
 
 ## Members
 
 `val callableId: CallableId?`
 : The fully-qualified name of a declaration, or `null` if the declaration is a local one.
 
 `val returnType: KaType`
-: The declaration's return type. For properties, a type of the property.
+: The declaration's return type. For properties, the type of the property.
 
 `val isExtension: Boolean`
 : `true` if the declaration is an extension function or an extension property.
@@ -37,8 +37,8 @@ overridden declaration for `C.foo`.
 
 `val KaCallableSymbol.allOverriddenSymbols: Sequence<KaCallableSymbol>`
 : A sequence of declarations overridden by the given declaration, both directly and indirectly.
-: E.g., if `A.foo` overrides `B.foo`, and `B.foo` overrides `C.foo`, both `A.foo` and `B.foo` will be returned as an
-overridden declaration for `C.foo`.
+: E.g., if `A.foo` overrides `B.foo`, and `B.foo` overrides `C.foo`, both `A.foo` and `B.foo` will be returned as
+overridden declarations for `C.foo`.
 
 `val KaCallableSymbol.fakeOverrideOriginal: KaCallableSymbol`
 : The original declared symbol for a substitution or intersection override.

Writerside/topics/KaClassLikeSymbol.md

@@ -1,6 +1,6 @@
 # KaClassLikeSymbol
 
-Represents a class, object, interface or a type alias declaration.
+Represents a class, object, interface, or a type alias declaration.
 
 ## Hierarchy
 

Writerside/topics/KaClassSymbol.md

@@ -1,6 +1,6 @@
 # KaClassSymbol
 
-Represents a class, object or an interface declaration.
+Represents a class, object, or interface declaration.
 
 ## Use Cases
 

Writerside/topics/KaDeclarationSymbol.md

@@ -1,6 +1,6 @@
 # KaDeclarationSymbol
 
-Represents a declaration, such as a class, function or property.
+Represents a declaration, such as a class, function, or property.
 
 ## Hierarchy
 
@@ -12,16 +12,16 @@ Inherits from [KaSymbol](KaSymbol.md), [KaAnnotated](Annotations.md#kaannotated)
 : A list of applied annotations.
 
 `val modality: KaSymbolModality`
-: Effective declaration modality (e.g., final, sealed or open).
+: Effective declaration modality (e.g., final, sealed, or open).
 
 `val visibility: KaSymbolVisibility`
-: Effective declaration visibility (e.g., public, protected or private).
+: Effective declaration visibility (e.g., public, protected, or private).
 
 `val isExpect: Boolean`
 : `true` if the declaration is an `expect` one.
 
 `val isActual: Boolean`
-: `true` if the declaration is an `actual `one.
+: `true` if the declaration is an `actual` one.
 
 `val KaDeclarationSymbol.typeParameters: List<KaTypeParameterSymbol>`
 : A list of type parameters for `KaTypeParameterOwnerSymbol`, an empty list otherwise.

Writerside/topics/KaEnumEntrySymbol.md

@@ -4,7 +4,7 @@ Represents an [enum entry](https://kotlinlang.org/docs/enum-classes.html) declar
 
 <note>
 In the Kotlin PSI, a <code>KtEnumEntry</code> is a <code>KtClass</code>, as it was so In the old compiler. 
-In Analysis API, though, similarly to the K2 compiler, it is a <code>KaVariableSymbol</code>.
+In the Analysis API, though, similarly to the K2 compiler, it is a <code>KaVariableSymbol</code>.
 </note>
 
 ## Hierarchy

Writerside/topics/KaFunctionSymbol.md

@@ -1,6 +1,6 @@
 # KaFunctionSymbol
 
-Represents a function-like declaration, including named and anonymous functions, constructors and property accessors.
+Represents a function-like declaration, including named and anonymous functions, constructors, and property accessors.
 
 ## Hierarchy
 

Writerside/topics/KaNamedClassSymbol.md

@@ -1,14 +1,14 @@
 # KaNamedClassSymbol
 
-Represents a named class, object or an interface declaration.  
+Represents a named class, object, or interface declaration.
 Basically, covers all class-like declarations, excluding anonymous objects.
 
 ## Use Cases
 
-* **Checking for specific class features.** Use properties like `isData`, `isInner`, and `isCompanion` to
-  determine if the class has specific characteristics.
+* **Checking for specific class features.** Use properties like `isData`, `isInner`, and `isCompanion` to determine if
+  the class has specific characteristics.
 
-Also see use-cases for the [KaClassSymbol](KaClassSymbol.md#use-cases) supertype.
+Also see use cases for the [KaClassSymbol](KaClassSymbol.md#use-cases) supertype.
 
 ## Hierarchy
 
@@ -17,7 +17,7 @@ Inherits from [KaClassSymbol](KaClassSymbol.md).
 ## Members
 
 `val name: Name`
-: The simple declaration name, e.g. `String` for `kotlin.String`.
+: The simple declaration name, e.g., `String` for `kotlin.String`.
 
 `val companionObject: KaNamedClassSymbol?`
 : The nested companion object, or `null` if there is no companion object.
@@ -27,7 +27,7 @@ Inherits from [KaClassSymbol](KaClassSymbol.md).
 : **Experimental API**.
 
 `val isExternal: Boolean`
-: `true` if the declaration has the `external modifier.
+: `true` if the declaration has the `external` modifier.
 
 `val isData: Boolean`
 : `true` if the declaration is a `data class`.
@@ -47,8 +47,8 @@ Inherits from [KaClassSymbol](KaClassSymbol.md).
 ## Type utilities
 
 `val KaNamedClassSymbol.defaultType: KaType`
-: A class type where type parameters are substituted with matching type parameter types, 
-e.g. `List<T>` for the `List` class.
+: A class type where type parameters are substituted with matching type parameter types, e.g., `List<T>` for the `List`
+class.
 
 ## Relation utilities