Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
IgnatBeresnev opened this issue Aug 11, 2023 · 4 comments
Open

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

IgnatBeresnev opened this issue Aug 11, 2023 · 4 comments
Assignees
Labels
feedback: Google An issue/PR submitted by colleagues at Google, most likely related to the Android API reference docs tech-debt A technical issue that is not observable by the users, but improves maintainers quality of life

Comments

@IgnatBeresnev
Copy link
Member

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 IgnatBeresnev self-assigned this Aug 11, 2023
@IgnatBeresnev IgnatBeresnev added the feedback: Google An issue/PR submitted by colleagues at Google, most likely related to the Android API reference docs label Aug 11, 2023
@IgnatBeresnev
Copy link
Member Author

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

  • ExternalDocumentablesProvider - should be made public and stable. Used for resolving supertypes.
  • org.intellij.markdown.MarkdownElementTypes.MARKDOWN_FILE - needs a public and stable substitution. The use case is the same as in Dokka: used as the default name for a doc tag, so it needs to be reflected in the name.
  • SampleTransformer - the interface SampleProvider introduced in Fix and refactor Sample Transformer #3102 will cover the use cases. Should be made public and stable, and we should add more details to the documentation so that the body-processing guarantees (such as whitespace trimming) are not lost.

Not planned:

  • KotlinToJavaService - not actually needed, can stay internal.
  • Transitive utility functions (everything from addToStdlib, com.jetbrains.rd.util and other packages) - no way for us to replace them.

@IgnatBeresnev
Copy link
Member Author

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:

  • Enums no longer extending the kotlin.Enum class
  • Classes that extend List or CoroutineContext have no inheritance information anymore.

@IgnatBeresnev
Copy link
Member Author

IgnatBeresnev commented Oct 10, 2023

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:

  • Having an enum (like the existing DocumentableLanguage) might be undesirable because there's no room for extension in 3rd party plugins or analyses. Not sure if it's a capability worth providing though.
  • This capability could be moved from an external interface/extension to be inside the WithSources interface, but WithSources is a bit misleading as it can exist even for declarations that do not have sources.

@IgnatBeresnev IgnatBeresnev added this to the Dokka 1.9.20 milestone Oct 12, 2023
@IgnatBeresnev IgnatBeresnev added the tech-debt A technical issue that is not observable by the users, but improves maintainers quality of life label Apr 8, 2024
@IgnatBeresnev
Copy link
Member Author

Blocked by #3573

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feedback: Google An issue/PR submitted by colleagues at Google, most likely related to the Android API reference docs tech-debt A technical issue that is not observable by the users, but improves maintainers quality of life
Projects
None yet
Development

No branches or pull requests

3 participants