/
SampleAnalysisEnvironmentCreator.kt
53 lines (48 loc) · 2.09 KB
/
SampleAnalysisEnvironmentCreator.kt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
/*
* Copyright 2014-2024 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 a 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
/**
* Creates a new instance of [SampleAnalysisEnvironment].
*
* **WARNING**: This function offers a considerable amount of freedom and with it,
* the potential to misuse the API.
* A [SampleAnalysisEnvironment] once created needs to be manually closed
* otherwise it could lead to memory leaks, concurrency issues or other unexpected problems.
*
* Therefore, it's safest to use it through the [SampleAnalysisEnvironmentCreator.use]
* as it provides a controlled environment where everything is taken care of automatically.
*
* @return a new instance of [SampleAnalysisEnvironment]
*/
public fun create(): SampleAnalysisEnvironment
}