Add documentation for in-memory file analysis #7
+242
−0
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
marcopennekamp
requested changes
Feb 13, 2025
| <note>Experimental API. Subject to changes.</note> | ||
|
|
||
| Parsing a Kotlin file does not require any knowledge about the project it belongs to. On the other hand, for *semantic | ||
| code analysis*, understanding dependencies and compilation options of file file is crucial. |
There was a problem hiding this comment.
Suggested change
| code analysis*, understanding dependencies and compilation options of file file is crucial. | |
| code analysis*, understanding dependencies and compilation options of a file is crucial. |
| scripts technically do not belong to any module. However, in such cases, the build system also provides the necessary | ||
| context. For example, Gradle build scripts include the Gradle API and all libraries Gradle depends on in their classpath. | ||
|
|
||
| In certain cases, it might be useful to analyze a file without storing it on the file system. For example, an IDE |
There was a problem hiding this comment.
Suggested change
| In certain cases, it might be useful to analyze a file without storing it on the file system. For example, an IDE | |
| In certain cases, it might be useful to analyze a file without storing it in the file system. For example, an IDE |
| ``` | ||
|
|
||
| The `contextModule` returned is of type `KaModule` which is an Analysis API abstraction over `Module`, `Library` and | ||
| `Sdk`concepts from IntelliJ IDEA. Specifically, a `KaSourceModule` represents a source module, and libraries and SDKs |
There was a problem hiding this comment.
Suggested change
| `Sdk`concepts from IntelliJ IDEA. Specifically, a `KaSourceModule` represents a source module, and libraries and SDKs | |
| `Sdk` concepts from IntelliJ IDEA. Specifically, a `KaSourceModule` represents a source module, and libraries and SDKs |
| val contextModule = KaModuleProvider.getModule(project, contextFile, useSiteModule = null) | ||
| ``` | ||
|
|
||
| The `contextModule` returned is of type `KaModule` which is an Analysis API abstraction over `Module`, `Library` and |
There was a problem hiding this comment.
Suggested change
| The `contextModule` returned is of type `KaModule` which is an Analysis API abstraction over `Module`, `Library` and | |
| The `contextModule` returned is of type `KaModule` which is an Analysis API abstraction over `Module`, `Library`, and |
|
|
||
| The `contextModule` returned is of type `KaModule` which is an Analysis API abstraction over `Module`, `Library` and | ||
| `Sdk`concepts from IntelliJ IDEA. Specifically, a `KaSourceModule` represents a source module, and libraries and SDKs | ||
| are represented by `KaLibraryModule`s. Every `KaSymbol` in the Analysis API is associated to some `KaModule`. |
There was a problem hiding this comment.
Suggested change
| are represented by `KaLibraryModule`s. Every `KaSymbol` in the Analysis API is associated to some `KaModule`. | |
| are represented by `KaLibraryModule`s. Every `KaSymbol` in the Analysis API is associated with some `KaModule`. |
Comment on lines
+71
to
+86
| If you already have a reference to a `Module`, you can convert it to a `KaModule` using one of the Kotlin plugin helper | ||
| functions: | ||
|
|
||
| ```kotlin | ||
| fun Module.toKaSourceModule(kind: KaSourceModuleKind): KaSourceModule? | ||
| fun Module.toKaSourceModuleForProduction(): KaSourceModule? | ||
| fun Module.toKaSourceModuleForTest(): KaSourceModule? | ||
| ``` | ||
|
|
||
| For more related APIs, refer to the Kotlin plugin's | ||
| [source code](https://github.com/JetBrains/intellij-community/blob/master/plugins/kotlin/base/project-structure/src/org/jetbrains/kotlin/idea/base/projectStructure/api.kt). | ||
| There are also overloads that accept `ModuleId` and `ModuleEntity` from the newer project model API. | ||
|
|
||
| In the `KaModuleProvider.getModule` function call, we passed `useSiteModule = null`. For advanced scenarios, | ||
| you might want to analyze files from other modules in the context of a synthetic module. In such cases, that synthetic | ||
| module can be passed as a `useSiteModule`. For typical use cases, it is safe to pass `null`. |
There was a problem hiding this comment.
I feel like there's a lot of detailed information here which breaks up the flow of the tutorial too much. Maybe some of these notes can be moved to a separate section?
| If the context module includes a dependency to the Kotlin Standard library, the analysis will no longer produce errors. | ||
|
|
||
| The created file can reference declarations from the context module, including `internal` ones. | ||
| However, no matter what is be written in our newly created file, it will not affect resolution of our context file. |
There was a problem hiding this comment.
Suggested change
| However, no matter what is be written in our newly created file, it will not affect resolution of our context file. | |
| However, no matter the content of our newly created file, it will not affect resolution of our context file. |
Comment on lines
+139
to
+144
| If you need a long-lived file that will be modified and analyzed multiple times, you should create a physical file: | ||
|
|
||
| ```kotlin | ||
| val factory = KtPsiFactory(project, eventSystemEnabled = true) | ||
| val file = factory.createFile(text) | ||
| ``` |
There was a problem hiding this comment.
I think it'd be nice here to note that the eventSystemEnabled setting is what makes the file physical. It's otherwise a bit hard to see and unintuitive.
Comment on lines
+162
to
+167
| The `copy()` function creates non-physical files. For this setup (a non-physical file with a `getOriginalFile()` set), | ||
| the Analysis API uses a different analysis strategy by default. | ||
|
|
||
| This behavior is optimized for efficiency. Since the original file might be large, analyzing it from scratch could be | ||
| unnecessarily resource-intensive. In most cases, file copies primarily differ in declaration bodies, so the Analysis API | ||
| leverages existing analysis results from the original file. |
There was a problem hiding this comment.
Looking at the analyzeCopy example below, I think it'd be nice to have an analyzeCopy example here without the PREFER_SELF mode, and then that note about the default mode.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.