Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.4k stars 399 forks source link

Migrate Google's devsite-plugin to analysis-kotlin-api #3112

Open IgnatBeresnev opened 1 year ago

IgnatBeresnev commented 1 year ago

Dokka 1.9.0 introduces some breaking changes that affect the plugin that builds Android's API reference docs.

This plugin uses significantly more compiler internals than any other Dokka plugin, so we need to provide stable alternatives for the now-missing API, and help with migration where possible.


Definition of done: dokka-devsite-plugin has migrated to analysis-kotlin-api, and no regression was noticed.

IgnatBeresnev commented 1 year ago

API-wise, what needs to be done from Dokka's side:

Not planned:

IgnatBeresnev commented 1 year ago

Regression-wise, there are some problems with inheritance, but it's unclear where it's coming from: might be the refactoring, might be the compiler, might be some custom logic in devsite plugin.

Examples:

IgnatBeresnev commented 11 months ago

New request: there should be some API that helps determine the source/origin language of a Documentable, to be able to say whether it's coming from Kotlin or Java code/analysis. Previously, the following check was possible:

(documentable as? WithSources).sources.entries.singleOrNull.value is PsiDocumentableSource

But the PsiDocumentableSource class is no longer available, it's now internal.


We have an internal alternative in the form of DocumentableSourceLanguageParser extension, so it might be enough to "stabilize" it by providing a clear contract and making it public.

Notes on the implementation:

IgnatBeresnev commented 4 months ago

Blocked by #3573