-
Notifications
You must be signed in to change notification settings - Fork 409
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Stabilize Sample analysis API (#3195)
- Loading branch information
1 parent
9ce37af
commit 6fbc222
Showing
35 changed files
with
1,216 additions
and
407 deletions.
There are no files selected for viewing
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
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
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
36 changes: 0 additions & 36 deletions
36
...kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/SampleProvider.kt
This file was deleted.
Oops, something went wrong.
43 changes: 43 additions & 0 deletions
43
...i/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironment.kt
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| /* | ||
| * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. | ||
| */ | ||
|
|
||
| package org.jetbrains.dokka.analysis.kotlin.sample | ||
|
|
||
| import org.jetbrains.dokka.DokkaConfiguration | ||
|
|
||
| /** | ||
| * Fully-configured and ready-to-use sample analysis environment. | ||
| * | ||
| * It's best to limit the scope of use and lifetime of this environment as it takes up | ||
| * additional resources which could be freed once the samples have been analyzed. | ||
| * Therefore, it's best to use it through the [SampleAnalysisEnvironmentCreator.use] lambda. | ||
| * | ||
| * For example, if you need to process all samples in an arbitrary project, it's best to do it | ||
| * in one iteration and at the same time, so that the environment is created once and lives for | ||
| * as little is possible, as opposed to creating it again and again for every individual sample. | ||
| */ | ||
| public interface SampleAnalysisEnvironment { | ||
|
|
||
| /** | ||
| * Resolves a Kotlin sample function by its fully qualified name, and returns its import statements and body. | ||
| * | ||
| * @param sourceSet must be either the source set in which this sample function resides, or the source set | ||
| * for which [DokkaConfiguration#samples] or [DokkaConfiguration#sourceRoots] | ||
| * have been configured with the sample's sources. | ||
| * @param fullyQualifiedLink fully qualified path to the sample function, including all middle packages | ||
| * and the name of the function. Only links to Kotlin functions are valid, | ||
| * which can reside within a class. The package must be the same as the package | ||
| * declared in the sample file. The function must be resolvable by Dokka, | ||
| * meaning it must reside either in the main sources of the project or its | ||
| * sources must be included in [DokkaConfiguration#samples] or | ||
| * [DokkaConfiguration#sourceRoots]. Example: `com.example.pckg.topLevelKotlinFunction` | ||
| * | ||
| * @return a sample code snippet which includes import statements and the function body, | ||
| * or null if the link could not be resolved (examine the logs to find out the reason). | ||
| */ | ||
| public fun resolveSample( | ||
| sourceSet: DokkaConfiguration.DokkaSourceSet, | ||
| fullyQualifiedLink: String | ||
| ): SampleSnippet? | ||
| } |
38 changes: 38 additions & 0 deletions
38
...ain/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| /* | ||
| * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. | ||
| */ | ||
|
|
||
| package org.jetbrains.dokka.analysis.kotlin.sample | ||
|
|
||
| import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin | ||
|
|
||
| /** | ||
| * Entry point to analyzing Kotlin samples. | ||
| * | ||
| * Can be acquired via [KotlinAnalysisPlugin.sampleAnalysisEnvironmentCreator]. | ||
| */ | ||
| public interface SampleAnalysisEnvironmentCreator { | ||
|
|
||
| /** | ||
| * Creates and configures the sample analysis environment for a limited-time use. | ||
| * | ||
| * Configuring sample analysis environment is a rather expensive operation that takes up additional | ||
| * resources since Dokka needs to configure and analyze source roots additional to the main ones. | ||
| * It's best to limit the scope of use and the lifetime of the created environment | ||
| * so that the resources could be freed as soon as possible. | ||
| * | ||
| * No specific cleanup is required by the caller - everything is taken care of automatically | ||
| * as soon as you exit the [block] block. | ||
| * | ||
| * Usage example: | ||
| * ```kotlin | ||
| * // create a short-lived environment and resolve all the needed samples | ||
| * val sample = sampleAnalysisEnvironmentCreator.use { | ||
| * resolveSample(sampleSourceSet, "org.jetbrains.dokka.sample.functionName") | ||
| * } | ||
| * // process the samples | ||
| * // ... | ||
| * ``` | ||
| */ | ||
| public fun <T> use(block: SampleAnalysisEnvironment.() -> T): T | ||
| } |
45 changes: 45 additions & 0 deletions
45
...is-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleSnippet.kt
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| /* | ||
| * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. | ||
| */ | ||
|
|
||
| package org.jetbrains.dokka.analysis.kotlin.sample | ||
|
|
||
| /** | ||
| * Represents a sample code snippet of a Kotlin function. The snippet includes both file | ||
| * import directives (all, even unused) and the sample function body. | ||
| * | ||
| * @property imports list of import statement values, without the `import` prefix. | ||
| * Contains no blank lines. Example of a single value: `com.example.pckg.MyClass.function`. | ||
| * @property body body of the sample function, without the function name or curly braces, only the inner body. | ||
| * Common minimal indent of all lines is trimmed. Leading and trailing line breaks are removed. | ||
| * Trailing whitespaces are removed. Example: given the sample function `fun foo() { println("foo") }`, | ||
| * the sample body will be `println("foo")`. | ||
| * | ||
| * @see SampleAnalysisEnvironment for how to acquire it | ||
| */ | ||
| public class SampleSnippet( | ||
| public val imports: List<String>, | ||
| public val body: String | ||
| ) { | ||
| override fun equals(other: Any?): Boolean { | ||
| if (this === other) return true | ||
| if (javaClass != other?.javaClass) return false | ||
|
|
||
| other as SampleSnippet | ||
|
|
||
| if (imports != other.imports) return false | ||
| if (body != other.body) return false | ||
|
|
||
| return true | ||
| } | ||
|
|
||
| override fun hashCode(): Int { | ||
| var result = imports.hashCode() | ||
| result = 31 * result + body.hashCode() | ||
| return result | ||
| } | ||
|
|
||
| override fun toString(): String { | ||
| return "SampleSnippet(imports=$imports, body='$body')" | ||
| } | ||
| } |
Oops, something went wrong.