Context

The API introduced for analyzing samples in #3195 does not fit Dackka (Google's plugin) well: Dokka works through processing batches of documentables in a pipeline, but Dackka has more of a service-like architecture, where it can invoke sample resolution from later stages.

Problem

Invoking SampleAnalysisEnvironmentCreator#use for every resolution request in Dackka leads to stalling and other problems. Refactoring the architecture to batch sample resolution is also tricky.

Solution

The following API was discussed with Google, and tested on Dackka, which seems to work and solve the problem stated above.

1. Make SampleAnalysisEnvironment closeable (java.io.Closeable).
2. Add public fun create(): SampleAnalysisEnvironment to SampleAnalysisEnvironmentCreator

The commit that has these changes: 2b6eb92 (sample-analysis-manual branch)

In order to merge these changes in, the following needs to be done:

1. Add a KDoc to SampleAnalysisEnvironmentCreator#create, stating that:
   • it's delicate API and should be avoided in favor of #use, because it can lead to memory leaks, concurrency issues or other unexpected problems, whereas use has a controlled environment.
   • the SampleAnalysisEnvironment that is created should be closed by the user manually, otherwise it may lead to leaks
2. Ideally, an opt-in annotation like @DelicateDokkaApi should be added, similar to DelicateCoroutinesApi.
3. Add unit tests (there is one test already, but maybe more are needed)

Other

The branch sample-analysis-manual may be revived, although it's not a requirement - a new branch can be created.