Skip to content

Commit c9e9f21

Browse files
yanexyanex
committed
Initial commit
0 parents  commit c9e9f21

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+3051
-0
lines changed

Diff for: ‎.github/workflows/build-docs.yml

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Build documentation
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
workflow_dispatch:
7+
8+
env:
9+
INSTANCE: 'Writerside/hi'
10+
ARTIFACT: 'webHelpHI2-all.zip'
11+
DOCKER_VERSION: '241.18775'
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Build docs using Writerside Docker builder
23+
uses: JetBrains/writerside-github-action@v4
24+
with:
25+
instance: ${{ env.INSTANCE }}
26+
artifact: ${{ env.ARTIFACT }}
27+
docker-version: ${{ env.DOCKER_VERSION }}
28+
29+
- name: Save artifact with build results
30+
uses: actions/upload-artifact@v4
31+
with:
32+
name: docs
33+
path: |
34+
artifacts/${{ env.ARTIFACT }}
35+
retention-days: 7

Diff for: ‎.idea/.gitignore

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎.idea/analysis-api-docs.iml

+8
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎.idea/modules.xml

+8
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎.idea/vcs.xml

+6
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎Writerside/c.list

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE categories SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
3+
<categories>
4+
<category id="wrs" name="Writerside documentation" order="1"/>
5+
</categories>

Diff for: ‎Writerside/hi.tree

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
3+
4+
<instance-profile id="hi" name="Analysis API Documentation" start-page="Index.md">
5+
<toc-element topic="Index.md"/>
6+
<toc-element topic="Fundamentals.md"/>
7+
<toc-element topic="Symbols.md">
8+
<toc-element topic="KaSymbol.md">
9+
</toc-element>
10+
<toc-element topic="KaDeclarationSymbol.md">
11+
</toc-element>
12+
<toc-element topic="KaClassifierSymbol.md">
13+
<toc-element topic="KaClassLikeSymbol.md">
14+
<toc-element topic="KaClassSymbol.md">
15+
<toc-element topic="KaNamedClassSymbol.md"/>
16+
<toc-element topic="KaAnonymousObjectSymbol.md"/>
17+
</toc-element>
18+
<toc-element topic="KaTypeAliasSymbol.md"/>
19+
</toc-element>
20+
<toc-element topic="KaTypeParameterSymbol.md"/>
21+
</toc-element>
22+
<toc-element topic="KaCallableSymbol.md">
23+
<toc-element topic="KaFunctionSymbol.md">
24+
<toc-element topic="KaNamedFunctionSymbol.md"/>
25+
<toc-element topic="KaAnonymousFunctionSymbol.md"/>
26+
<toc-element topic="KaConstructorSymbol.md"/>
27+
<toc-element topic="KaPropertyAccessorSymbol.md"/>
28+
</toc-element>
29+
<toc-element topic="KaVariableSymbol.md">
30+
<toc-element topic="KaPropertySymbol.md"/>
31+
<toc-element topic="KaValueParameterSymbol.md"/>
32+
<toc-element topic="KaLocalVariableSymbol.md"/>
33+
<toc-element topic="KaBackingFieldSymbol.md"/>
34+
<toc-element topic="KaEnumEntrySymbol.md"/>
35+
</toc-element>
36+
</toc-element>
37+
</toc-element>
38+
<toc-element topic="Scopes.md"/>
39+
<toc-element topic="Types.md">
40+
<toc-element topic="KaType.md">
41+
<toc-element topic="KaClassType.md">
42+
<toc-element topic="KaUsualClassType.md"/>
43+
<toc-element topic="KaFunctionType.md"/>
44+
</toc-element>
45+
<toc-element topic="KaTypeParameterType.md"/>
46+
<toc-element topic="KaDefinitelyNotNullType.md"/>
47+
<toc-element topic="KaIntersectionType.md"/>
48+
<toc-element topic="KaCapturedType.md"/>
49+
<toc-element topic="KaFlexibleType.md"/>
50+
<toc-element topic="KaDynamicType.md"/>
51+
<toc-element topic="KaErrorType.md">
52+
<toc-element topic="KaClassErrorType.md"/>
53+
</toc-element>
54+
</toc-element>
55+
<toc-element topic="KaTypeProjection.md"/>
56+
</toc-element>
57+
<toc-element topic="Annotations.md">
58+
<toc-element topic="KaAnnotation.md"/>
59+
<toc-element topic="KaAnnotationValue.md"/>
60+
</toc-element>
61+
<toc-element topic="References-And-Calls.md">
62+
<toc-element topic="KaCall.md">
63+
<toc-element topic="KaCallableMemberCall.md">
64+
<toc-element topic="KaFunctionCall.md">
65+
<toc-element topic="KaSimpleFunctionCall.md"/>
66+
<toc-element topic="KaDelegatedConstructorCall.md"/>
67+
<toc-element topic="KaAnnotationCall.md"/>
68+
</toc-element>
69+
<toc-element topic="KaVariableAccessCall.md">
70+
</toc-element>
71+
<toc-element topic="KaCompoundVariableAccessCall.md"/>
72+
<toc-element topic="KaCompoundArrayAccessCall.md"/>
73+
</toc-element>
74+
</toc-element>
75+
<toc-element topic="Receivers.md"/>
76+
</toc-element>
77+
<toc-element topic="Other.md">
78+
<toc-element topic="Java-Kotlin-Bridging.md"/>
79+
<toc-element topic="Diagnostics.md">
80+
<toc-element topic="KaDiagnostic.md">
81+
</toc-element>
82+
<toc-element topic="KaDiagnosticWithPsi.md"/>
83+
</toc-element>
84+
<toc-element topic="File-Compilation.md"/>
85+
</toc-element>
86+
<toc-element topic="Guides.md">
87+
<toc-element topic="Migration-from-K1.md"/>
88+
<toc-element topic="Migrating-Inspections.md"/>
89+
<toc-element topic="Migrating-Intentions.md"/>
90+
<toc-element topic="Using-Light-Classes.md"/>
91+
</toc-element>
92+
</instance-profile>

Diff for: ‎Writerside/redirection-rules.xml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE rules SYSTEM "https://resources.jetbrains.com/writerside/1.0/redirection-rules.dtd">
3+
<rules>
4+
<!-- format is as follows
5+
<rule id="<unique id>">
6+
<accepts>page.html</accepts>
7+
</rule>
8+
-->
9+
</rules>

Diff for: ‎Writerside/topics/Annotations.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Annotations
2+
3+
Annotations play a crucial role in Kotlin, providing metadata and influencing code behavior. Analysis API allows you
4+
to access and analyze annotations applied to both declarations and types.
5+
6+
## KaAnnotated
7+
8+
`KaAnnotated` is an interface exposing a list of annotations. All [types](Types.md) and almost all
9+
[symbols](Symbols.md) implement it.
10+
11+
<code-block lang="mermaid">
12+
graph TD
13+
KaAnnotated
14+
KaAnnotated --> KaType
15+
KaAnnotated --> KaAnnotatedSymbol
16+
KaAnnotatedSymbol --> KaFileSymbol
17+
KaAnnotatedSymbol --> KaScriptSymbol
18+
KaAnnotatedSymbol --> KaDeclarationSymbol
19+
</code-block>
20+
21+
The only property `KaAnnotated` declares is `annotations` of the `KaAnnotationList` type. `KaAnnotationList` itself
22+
is implements a `List<KaAnnotation>`, so you can directly iterate over annotations:
23+
24+
```Kotlin
25+
fun KaSession.processAnnotations(symbol: KaDeclarationSymbol) {
26+
for (anno in symbol.annotations) {
27+
// Process the 'annotation'
28+
}
29+
}
30+
```
31+
32+
`KaAnnotationsList` is not just a list. It can also efficiently check whether an annotation with some `ClassId`
33+
is there:
34+
35+
```Kotlin
36+
fun KaSession.hasDeprecatedAnnotation(symbol: KaDeclarationSymbol) {
37+
val classId = ClassId.fromString("kotlin/Deprecated")
38+
return classId in symbol.annotations
39+
}
40+
```
41+
42+
You can also get a list of annotations with a specific `ClassId`. Kotlin allows repeatable annotations, so a list
43+
of them is returned:
44+
45+
```Kotlin
46+
fun KaSession.findDeprecatedAnnotation(symbol: KaDeclarationSymbol): KaAnnotation? {
47+
val classId = ClassId.fromString("kotlin/Deprecated")
48+
return symbol.annotations[classId].firstOrNull()
49+
}
50+
```
51+
52+
Finally, `KaAnnotationList` exposes a collection of all annotation `ClassId`s:
53+
54+
```Kotlin
55+
fun KaSession.collectAnnotations(types: List<KaType>): Set<ClassId> {
56+
return types.flatMapTo(HashSet()) { it.annotations.classIds }
57+
}
58+
```
59+
60+
## Use-Site Targets
61+
62+
Annotations on declarations can have use-site targets, specifying where the annotation applies (e.g., property, field,
63+
or parameter). You can use the `useSiteTarget` property of `KtAnnotation` to access this information.

Diff for: ‎Writerside/topics/Diagnostics.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Diagnostics
2+
3+
Analysis API allows you to access and analyze compiler diagnostics (errors and warnings) associated with entire files
4+
or specific elements.
5+
6+
## Diagnostics in a `KtFile`
7+
8+
To collect diagnostics for an entire file, use `collectDiagnostics()`:
9+
10+
```kotlin
11+
analyze(ktFile) {
12+
val diagnostics = ktFile
13+
.collectDiagnostics(KaDiagnosticCheckerFilter.ONLY_COMMON_CHECKERS)
14+
.filterIsInstance<KaFirDiagnostic.WrongAnnotationTarget>()
15+
}
16+
```
17+
18+
The `KaDiagnosticCheckerFilter` enum allows you to control which kinds of diagnostics are included:
19+
20+
* `ONLY_COMMON_CHECKERS`: Includes diagnostics only from the compiler checkers.
21+
* `ONLY_EXTENDED_CHECKERS`: Includes diagnostics from extended checkers (that typically run only in the IDE).
22+
* `EXTENDED_AND_COMMON_CHECKERS`: Includes diagnostics from both common and extended checkers.
23+
24+
## Diagnostics on an element
25+
26+
<note>Experimental API. Subject to changes.</note>
27+
28+
To get diagnostics for a specific element, use `diagnostics`:
29+
30+
```kotlin
31+
analyze(ktElement) {
32+
val diagnostics = ktElement
33+
.diagnostics(KaDiagnosticCheckerFilter.ONLY_COMMON_CHECKERS)
34+
}
35+
```
36+
37+
Note that the returned list of diagnostics does not include diagnostics for nested `KtElement`s.
38+
39+
## `KtDiagnosticWithPsi`
40+
41+
`collectDiagnostics` and `diagnostics` return a collection of `KtDiagnosticWithPsi` instances.
42+
This interface provides access to information about the diagnostic.
43+
44+
45+
46+
| Member | Description |
47+
|------------------|-------------------------------------------------------------------------------|
48+
| `severity` | The severity of the diagnostic (e.g., `ERROR`, `WARNING`). |
49+
| `factoryName` | The name of the diagnostic factory that produced the diagnostic. |
50+
| `defaultMessage` | The default message associated with the diagnostic. |
51+
| `psi` | The `PsiElement` to which the diagnostic is attached. |
52+
| `textRanges` | The text ranges within the `psi` element that are relevant to the diagnostic. |

Diff for: ‎Writerside/topics/File-Compilation.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# File Compilation
2+
3+
<note>Experimental API. Subject to changes.</note>
4+
5+
Analysis API enables in-memory compilation of Kotlin files. This allows your tools and plugins to generate and compile
6+
Kotlin code without writing files to disk or invoking the command-line compiler.
7+
8+
## Usage
9+
10+
To compile Kotlin code, you need to provide:
11+
12+
* `KtFile`: The Kotlin file to compile (might be a `KtCodeFragment`);
13+
* `CompilerConfiguration`: A configuration instance containing compiler settings, such as a module name, and a target
14+
language version;
15+
* `KaCompilerTarget`: The target platform for compilation (currently, only JVM is supported
16+
with `KaCompilerTarget.Jvm`);
17+
* `allowedErrorFilter`: A function that filters allowed diagnostics. Compilation fails if there are errors
18+
that this function rejects.
19+
20+
Here's an example of compiling a `KtFile`:
21+
22+
```kotlin
23+
@RequiresReadLock
24+
@OptIn(KaExperimentalApi::class)
25+
fun performCompilation(file: KtFile): List<ByteArray> {
26+
val configuration = CompilerConfiguration() // configure compiler settings
27+
val target = KaCompilerTarget.Jvm(ClassBuilderFactories.BINARIES)
28+
29+
analyze(file) {
30+
val result = useSiteSession.compile(file, configuration, target) {
31+
// Filter allowed diagnostics (optional)
32+
it.severity != KaSeverity.ERROR
33+
}
34+
35+
when (result) {
36+
is KaCompilationResult.Success -> {
37+
// Process compiled output
38+
return result.output.map { it.content }
39+
}
40+
is KaCompilationResult.Failure -> {
41+
// Handle compilation errors
42+
throw RuntimeException("Compilation failed: ${result.errors}")
43+
}
44+
}
45+
}
46+
}
47+
```
48+
49+
The `compile` function throws a `KaCodeCompilationException` if any unexpected errors occur during compilation.
50+
Handle this exception appropriately in your code.
51+
52+
## KaCompilationResult
53+
54+
The `compile` function returns a `KaCompilationResult`, which can be either:
55+
56+
* `KaCompilationResult.Success`: Compilation was successful. You can access the generated output files through
57+
the `output` property.
58+
* `KaCompilationResult.Failure`: Compilation failed due to errors. The `errors` property contains a list of the
59+
encountered diagnostics.
60+
61+
## Output Files
62+
63+
The `output` property of `KaCompilationResult.Success` provides a list of `KaCompiledFile` instances, each containing:
64+
65+
`val path: String`
66+
: The relative path of the compiled file.
67+
68+
`val sourceFiles: List<File>`
69+
: The source files that contributed to the compiled file.
70+
71+
`val content: ByteArray`
72+
: The content of the compiled file as a byte array.

0 commit comments

Comments
 (0)