From 50fdc2128f80801a45c32330695b8649430af24a Mon Sep 17 00:00:00 2001 From: Marco Pennekamp Date: Tue, 31 Oct 2023 13:07:46 +0100 Subject: [PATCH] [AA] Improve documentation of `ProjectStructureProvider.getModule` - Since this documentation was written, the usages of contextual modules have expanded beyond outsider files, for example to support `KtModule` disambiguation for library elements. Hence, it was necessary to update the documentation accordingly. --- .../structure/ProjectStructureProvider.kt | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/analysis/project-structure/src/org/jetbrains/kotlin/analysis/project/structure/ProjectStructureProvider.kt b/analysis/project-structure/src/org/jetbrains/kotlin/analysis/project/structure/ProjectStructureProvider.kt index 4b59c012654..4097815da72 100644 --- a/analysis/project-structure/src/org/jetbrains/kotlin/analysis/project/structure/ProjectStructureProvider.kt +++ b/analysis/project-structure/src/org/jetbrains/kotlin/analysis/project/structure/ProjectStructureProvider.kt @@ -12,17 +12,25 @@ import org.jetbrains.kotlin.config.LanguageVersionSettingsImpl public abstract class ProjectStructureProvider { /** - * Returns a [KtModule] for a given [element] in context of the [contextualModule]. + * Returns a [KtModule] for a given [element] in the context of the [contextualModule]. + * + * The contextual module is the [KtModule] from which [getModule] is called. It is a way to disambiguate the [KtModule] of [element]s + * with whom multiple modules might be associated. In particular: + * + * 1. It allows replacing the original [KtModule] of [element] with another module, e.g. for supporting outsider files (see below). + * 2. It helps to distinguish between multiple possible [KtModule]s for library elements. + * + * #### Outsider Modules * * Normally, every Kotlin source file either belongs to some module (e.g. a source module, or a library module), or is self-contained * (a script file, or a file outside content roots). However, in certain cases there might be special modules that include both * existing source files, and also some additional files. * * An example of such a module is one that owns an 'outsider' source file. Outsiders are used in IntelliJ for displaying files that - * technically belong to some module, but are not included in the module's content roots (e.g. a file from previous VCS revision). + * technically belong to some module, but are not included in the module's content roots (e.g. a file from a previous VCS revision). * As there might be cross-references between the outsider file and other files in the module, they need to be analyzed as a single - * synthetic module. Inside an analysis session for such a module (that would become there a 'contextualModule'), - * sources that originally belong to a source module should be treated rather as a part of the synthetic one. + * synthetic module. Inside an analysis session for such a module (which would be the [contextualModule]), sources that originally + * belong to a source module should be treated rather as a part of the synthetic one. */ public abstract fun getModule(element: PsiElement, contextualModule: KtModule?): KtModule