From 8e5c63d035ef44a269b8c43430f43f5c8eebfb63 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 10 Nov 2023 11:46:54 +0100 Subject: Restructure the project to utilize included builds (#3174) * Refactor and simplify artifact publishing * Update Gradle to 8.4 * Refactor and simplify convention plugins and build scripts Fixes #3132 --------- Co-authored-by: Adam <897017+aSemy@users.noreply.github.com> Co-authored-by: Oleg Yukhnevich --- .../kotlin/org/jetbrains/dokka/base/DokkaBase.kt | 299 ++++++ .../jetbrains/dokka/base/DokkaBaseConfiguration.kt | 28 + .../base/deprecated/AnalysisApiDeprecatedError.kt | 16 + .../base/deprecated/KotlinAnalysisDeprecatedApi.kt | 77 ++ .../dokka/base/deprecated/ParsersDeprecatedAPI.kt | 42 + .../deprecated/ParsersFactoriesDeprecatedAPI.kt | 24 + .../TranslatorDescriptorsDeprecatedAPI.kt | 50 + .../base/deprecated/TranslatorPsiDeprecatedAPI.kt | 25 + .../base/generation/SingleModuleGeneration.kt | 131 +++ .../dokka/base/renderers/DefaultRenderer.kt | 257 +++++ .../jetbrains/dokka/base/renderers/FileWriter.kt | 109 +++ .../jetbrains/dokka/base/renderers/OutputWriter.kt | 11 + .../dokka/base/renderers/PackageListService.kt | 80 ++ .../dokka/base/renderers/TabSortingStrategy.kt | 11 + .../dokka/base/renderers/contentTypeChecking.kt | 24 + .../dokka/base/renderers/html/HtmlContent.kt | 18 + .../dokka/base/renderers/html/HtmlRenderer.kt | 1013 ++++++++++++++++++++ .../base/renderers/html/NavigationDataProvider.kt | 134 +++ .../dokka/base/renderers/html/NavigationPage.kt | 129 +++ .../base/renderers/html/SearchbarDataInstaller.kt | 128 +++ .../jetbrains/dokka/base/renderers/html/Tags.kt | 82 ++ .../consumers/ImmediateResolutionTagConsumer.kt | 37 + .../html/command/consumers/PathToRootConsumer.kt | 26 + .../command/consumers/ReplaceVersionsConsumer.kt | 29 + .../html/command/consumers/ResolveLinkConsumer.kt | 34 + .../base/renderers/html/htmlFormatingUtils.kt | 67 ++ .../dokka/base/renderers/html/htmlPreprocessors.kt | 172 ++++ .../innerTemplating/DefaultTemplateModelFactory.kt | 234 +++++ .../innerTemplating/DefaultTemplateModelMerger.kt | 20 + .../html/innerTemplating/HtmlTemplater.kt | 82 ++ .../html/innerTemplating/TemplateModelFactory.kt | 19 + .../html/innerTemplating/TemplateModelMerger.kt | 9 + .../renderers/html/shouldRenderSourceSetBubbles.kt | 20 + .../org/jetbrains/dokka/base/renderers/pageId.kt | 31 + .../dokka/base/renderers/preprocessors.kt | 41 + .../dokka/base/resolvers/anchors/AnchorsHint.kt | 19 + .../external/DefaultExternalLocationProvider.kt | 46 + .../DefaultExternalLocationProviderFactory.kt | 28 + .../external/Dokka010ExternalLocationProvider.kt | 46 + .../resolvers/external/ExternalLocationProvider.kt | 18 + .../external/ExternalLocationProviderFactory.kt | 11 + .../ExternalLocationProviderFactoryWithCache.kt | 21 + .../javadoc/AndroidExternalLocationProvider.kt | 18 + .../javadoc/JavadocExternalLocationProvider.kt | 62 ++ .../JavadocExternalLocationProviderFactory.kt | 39 + .../resolvers/local/DefaultLocationProvider.kt | 82 ++ .../resolvers/local/DokkaBaseLocationProvider.kt | 27 + .../base/resolvers/local/DokkaLocationProvider.kt | 182 ++++ .../local/DokkaLocationProviderFactory.kt | 26 + .../dokka/base/resolvers/local/LocationProvider.kt | 47 + .../resolvers/local/LocationProviderFactory.kt | 11 + .../base/resolvers/shared/ExternalDocumentation.kt | 9 + .../dokka/base/resolvers/shared/LinkFormat.kt | 10 + .../dokka/base/resolvers/shared/PackageList.kt | 83 ++ .../base/resolvers/shared/RecognizedLinkFormat.kt | 29 + .../jetbrains/dokka/base/resolvers/shared/utils.kt | 41 + .../dokka/base/signatures/JvmSignatureUtils.kt | 231 +++++ .../base/signatures/KotlinSignatureProvider.kt | 503 ++++++++++ .../dokka/base/signatures/KotlinSignatureUtils.kt | 86 ++ .../dokka/base/signatures/SignatureProvider.kt | 12 + .../base/templating/AddToNavigationCommand.kt | 9 + .../jetbrains/dokka/base/templating/AddToSearch.kt | 12 + .../base/templating/AddToSourcesetDependencies.kt | 10 + .../org/jetbrains/dokka/base/templating/Command.kt | 15 + .../templating/ImmediateHtmlCommandConsumer.kt | 17 + .../dokka/base/templating/InsertTemplateExtra.kt | 16 + .../templating/PathToRootSubstitutionCommand.kt | 10 + .../templating/ProjectNameSubstitutionCommand.kt | 10 + .../base/templating/ReplaceVersionsCommand.kt | 7 + .../dokka/base/templating/ResolveLinkCommand.kt | 11 + .../dokka/base/templating/jsonMapperForPlugins.kt | 62 ++ .../documentables/ActualTypealiasAdder.kt | 127 +++ .../documentables/ClashingDriIdentifier.kt | 12 + .../documentables/DefaultDocumentableMerger.kt | 0 .../DeprecatedDocumentableFilterTransformer.kt | 62 ++ .../DocumentableReplacerTransformer.kt | 239 +++++ .../DocumentableVisibilityFilterTransformer.kt | 388 ++++++++ .../documentables/EmptyModulesFilterTransformer.kt | 14 + .../EmptyPackagesFilterTransformer.kt | 30 + .../documentables/ExtensionExtractorTransformer.kt | 160 ++++ ...nheritedEntriesDocumentableFilterTransformer.kt | 23 + .../InheritorsExtractorTransformer.kt | 91 ++ .../KotlinArrayDocumentableReplacerTransformer.kt | 68 ++ .../ModuleAndPackageDocumentationTransformer.kt | 47 + ...bviousFunctionsDocumentableFilterTransformer.kt | 17 + .../documentables/ReportUndocumentedTransformer.kt | 143 +++ .../documentables/SuppressTagDocumentableFilter.kt | 17 + ...ssedByConditionDocumentableFilterTransformer.kt | 146 +++ ...ByConfigurationDocumentableFilterTransformer.kt | 57 ++ .../dokka/base/transformers/documentables/utils.kt | 35 + .../pages/DefaultSamplesTransformer.kt | 117 +++ .../pages/annotations/SinceKotlinTransformer.kt | 186 ++++ .../pages/comments/CommentsToContentConverter.kt | 22 + .../pages/comments/DocTagToContentConverter.kt | 270 ++++++ .../pages/merger/FallbackPageMergerStrategy.kt | 22 + .../base/transformers/pages/merger/PageMerger.kt | 40 + .../pages/merger/PageMergerStrategy.kt | 13 + .../merger/SameMethodNamePageMergerStrategy.kt | 68 ++ .../merger/SourceSetMergingPageTransformer.kt | 43 + .../pages/sourcelinks/SourceLinksTransformer.kt | 140 +++ .../pages/tags/CustomTagContentProvider.kt | 63 ++ .../pages/tags/SinceKotlinTagContentProvider.kt | 38 + .../DefaultDocumentableToPageTranslator.kt | 34 + .../documentables/DefaultPageCreator.kt | 779 +++++++++++++++ .../documentables/DeprecationSectionCreator.kt | 194 ++++ .../documentables/DescriptionSections.kt | 349 +++++++ .../translators/documentables/DriClashAwareName.kt | 13 + .../documentables/PageContentBuilder.kt | 781 +++++++++++++++ .../documentables/briefFromContentNodes.kt | 62 ++ .../dokka/base/utils/CollectionExtensions.kt | 16 + .../dokka/base/utils/alphabeticalOrder.kt | 11 + 111 files changed, 10312 insertions(+) create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBase.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBaseConfiguration.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/AnalysisApiDeprecatedError.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/KotlinAnalysisDeprecatedApi.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersDeprecatedAPI.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersFactoriesDeprecatedAPI.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorDescriptorsDeprecatedAPI.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorPsiDeprecatedAPI.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/generation/SingleModuleGeneration.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/DefaultRenderer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/FileWriter.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/OutputWriter.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/PackageListService.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/TabSortingStrategy.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/contentTypeChecking.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/HtmlContent.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/HtmlRenderer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/NavigationDataProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/NavigationPage.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/SearchbarDataInstaller.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/Tags.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/command/consumers/ImmediateResolutionTagConsumer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/command/consumers/PathToRootConsumer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/command/consumers/ReplaceVersionsConsumer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/command/consumers/ResolveLinkConsumer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/htmlFormatingUtils.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/htmlPreprocessors.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/innerTemplating/DefaultTemplateModelMerger.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/innerTemplating/HtmlTemplater.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/innerTemplating/TemplateModelFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/innerTemplating/TemplateModelMerger.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/shouldRenderSourceSetBubbles.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/pageId.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/preprocessors.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/anchors/AnchorsHint.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/DefaultExternalLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/DefaultExternalLocationProviderFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/Dokka010ExternalLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/ExternalLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/ExternalLocationProviderFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/ExternalLocationProviderFactoryWithCache.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/javadoc/AndroidExternalLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/javadoc/JavadocExternalLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/external/javadoc/JavadocExternalLocationProviderFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/DefaultLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/DokkaBaseLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/DokkaLocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/DokkaLocationProviderFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/LocationProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/local/LocationProviderFactory.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/shared/ExternalDocumentation.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/shared/LinkFormat.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/shared/PackageList.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/shared/RecognizedLinkFormat.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/resolvers/shared/utils.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/signatures/JvmSignatureUtils.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/signatures/KotlinSignatureProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/signatures/KotlinSignatureUtils.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/signatures/SignatureProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/AddToNavigationCommand.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/AddToSearch.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/AddToSourcesetDependencies.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/Command.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/ImmediateHtmlCommandConsumer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/InsertTemplateExtra.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/PathToRootSubstitutionCommand.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/ProjectNameSubstitutionCommand.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/ReplaceVersionsCommand.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/ResolveLinkCommand.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/templating/jsonMapperForPlugins.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ActualTypealiasAdder.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ClashingDriIdentifier.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/DefaultDocumentableMerger.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/DocumentableReplacerTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/DocumentableVisibilityFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/EmptyModulesFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/EmptyPackagesFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ExtensionExtractorTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/InheritedEntriesDocumentableFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/InheritorsExtractorTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/KotlinArrayDocumentableReplacerTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ObviousFunctionsDocumentableFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/ReportUndocumentedTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/SuppressTagDocumentableFilter.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/SuppressedByConditionDocumentableFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/SuppressedByConfigurationDocumentableFilterTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/documentables/utils.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/comments/DocTagToContentConverter.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/merger/FallbackPageMergerStrategy.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/merger/PageMerger.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/merger/PageMergerStrategy.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/merger/SameMethodNamePageMergerStrategy.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/merger/SourceSetMergingPageTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/sourcelinks/SourceLinksTransformer.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultDocumentableToPageTranslator.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DeprecationSectionCreator.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DescriptionSections.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DriClashAwareName.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/PageContentBuilder.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/briefFromContentNodes.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/utils/CollectionExtensions.kt create mode 100644 dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/utils/alphabeticalOrder.kt (limited to 'dokka-subprojects/plugin-base/src/main/kotlin/org') diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBase.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBase.kt new file mode 100644 index 00000000..ca86d4d5 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBase.kt @@ -0,0 +1,299 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.base + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.base.generation.SingleModuleGeneration +import org.jetbrains.dokka.base.renderers.* +import org.jetbrains.dokka.base.renderers.html.* +import org.jetbrains.dokka.base.renderers.html.command.consumers.PathToRootConsumer +import org.jetbrains.dokka.base.renderers.html.command.consumers.ReplaceVersionsConsumer +import org.jetbrains.dokka.base.renderers.html.command.consumers.ResolveLinkConsumer +import org.jetbrains.dokka.base.resolvers.external.DefaultExternalLocationProviderFactory +import org.jetbrains.dokka.base.resolvers.external.ExternalLocationProviderFactory +import org.jetbrains.dokka.base.resolvers.external.javadoc.JavadocExternalLocationProviderFactory +import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory +import org.jetbrains.dokka.base.resolvers.local.LocationProviderFactory +import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat +import org.jetbrains.dokka.base.signatures.KotlinSignatureProvider +import org.jetbrains.dokka.base.signatures.SignatureProvider +import org.jetbrains.dokka.base.templating.ImmediateHtmlCommandConsumer +import org.jetbrains.dokka.base.transformers.documentables.* +import org.jetbrains.dokka.base.transformers.pages.DefaultSamplesTransformer +import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer +import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter +import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter +import org.jetbrains.dokka.base.transformers.pages.merger.* +import org.jetbrains.dokka.base.transformers.pages.sourcelinks.SourceLinksTransformer +import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider +import org.jetbrains.dokka.base.transformers.pages.tags.SinceKotlinTagContentProvider +import org.jetbrains.dokka.base.translators.documentables.DefaultDocumentableToPageTranslator +import org.jetbrains.dokka.generation.Generation +import org.jetbrains.dokka.plugability.* +import org.jetbrains.dokka.renderers.Renderer +import org.jetbrains.dokka.transformers.documentation.* +import org.jetbrains.dokka.transformers.pages.PageTransformer + +@Suppress("unused") +public class DokkaBase : DokkaPlugin() { + + public val preMergeDocumentableTransformer: ExtensionPoint by extensionPoint() + public val pageMergerStrategy: ExtensionPoint by extensionPoint() + public val commentsToContentConverter: ExtensionPoint by extensionPoint() + public val customTagContentProvider: ExtensionPoint by extensionPoint() + public val signatureProvider: ExtensionPoint by extensionPoint() + public val locationProviderFactory: ExtensionPoint by extensionPoint() + public val externalLocationProviderFactory: ExtensionPoint by extensionPoint() + public val outputWriter: ExtensionPoint by extensionPoint() + public val htmlPreprocessors: ExtensionPoint by extensionPoint() + + @Deprecated("It is not used anymore") + public val tabSortingStrategy: ExtensionPoint by extensionPoint() + public val immediateHtmlCommandConsumer: ExtensionPoint by extensionPoint() + + + public val singleGeneration: Extension by extending { + CoreExtensions.generation providing ::SingleModuleGeneration + } + + public val documentableMerger: Extension by extending { + CoreExtensions.documentableMerger providing ::DefaultDocumentableMerger + } + + public val deprecatedDocumentableFilter: Extension by extending { + preMergeDocumentableTransformer providing ::DeprecatedDocumentableFilterTransformer + } + + public val suppressedDocumentableFilter: Extension by extending { + preMergeDocumentableTransformer providing ::SuppressedByConfigurationDocumentableFilterTransformer + } + + public val suppressedBySuppressTagDocumentableFilter: Extension by extending { + preMergeDocumentableTransformer providing ::SuppressTagDocumentableFilter + } + + public val documentableVisibilityFilter: Extension by extending { + preMergeDocumentableTransformer providing ::DocumentableVisibilityFilterTransformer + } + + public val obviousFunctionsVisbilityFilter: Extension by extending { + preMergeDocumentableTransformer providing ::ObviousFunctionsDocumentableFilterTransformer + } + + public val inheritedEntriesVisbilityFilter: Extension by extending { + preMergeDocumentableTransformer providing ::InheritedEntriesDocumentableFilterTransformer + } + + public val kotlinArrayDocumentableReplacer: Extension by extending { + preMergeDocumentableTransformer providing ::KotlinArrayDocumentableReplacerTransformer + } + + public val emptyPackagesFilter: Extension by extending { + preMergeDocumentableTransformer providing ::EmptyPackagesFilterTransformer order { + after( + deprecatedDocumentableFilter, + suppressedDocumentableFilter, + documentableVisibilityFilter, + suppressedBySuppressTagDocumentableFilter, + obviousFunctionsVisbilityFilter, + inheritedEntriesVisbilityFilter, + ) + } + } + + public val emptyModulesFilter: Extension by extending { + preMergeDocumentableTransformer with EmptyModulesFilterTransformer() order { + after(emptyPackagesFilter) + } + } + + public val modulesAndPackagesDocumentation: Extension by extending { + preMergeDocumentableTransformer providing ::ModuleAndPackageDocumentationTransformer + } + + public val actualTypealiasAdder: Extension by extending { + CoreExtensions.documentableTransformer with ActualTypealiasAdder() + } + + public val kotlinSignatureProvider: Extension by extending { + signatureProvider providing ::KotlinSignatureProvider + } + + public val sinceKotlinTransformer: Extension by extending { + CoreExtensions.documentableTransformer providing ::SinceKotlinTransformer applyIf { + SinceKotlinTransformer.shouldDisplaySinceKotlin() + } order { + before(extensionsExtractor) + } + } + + public val inheritorsExtractor: Extension by extending { + CoreExtensions.documentableTransformer with InheritorsExtractorTransformer() + } + + public val undocumentedCodeReporter: Extension by extending { + CoreExtensions.documentableTransformer with ReportUndocumentedTransformer() + } + + public val extensionsExtractor: Extension by extending { + CoreExtensions.documentableTransformer with ExtensionExtractorTransformer() + } + + public val documentableToPageTranslator: Extension by extending { + CoreExtensions.documentableToPageTranslator providing ::DefaultDocumentableToPageTranslator + } + + public val docTagToContentConverter: Extension by extending { + commentsToContentConverter with DocTagToContentConverter() + } + + public val sinceKotlinTagContentProvider: Extension by extending { + customTagContentProvider with SinceKotlinTagContentProvider applyIf { + SinceKotlinTransformer.shouldDisplaySinceKotlin() + } + } + + public val pageMerger: Extension by extending { + CoreExtensions.pageTransformer providing ::PageMerger + } + + public val sourceSetMerger: Extension by extending { + CoreExtensions.pageTransformer providing ::SourceSetMergingPageTransformer + } + + public val fallbackMerger: Extension by extending { + pageMergerStrategy providing { ctx -> FallbackPageMergerStrategy(ctx.logger) } + } + + public val sameMethodNameMerger: Extension by extending { + pageMergerStrategy providing { ctx -> SameMethodNamePageMergerStrategy(ctx.logger) } order { + before(fallbackMerger) + } + } + + public val htmlRenderer: Extension by extending { + CoreExtensions.renderer providing ::HtmlRenderer + } + + public val locationProvider: Extension by extending { + locationProviderFactory providing ::DokkaLocationProviderFactory + } + + public val javadocLocationProvider: Extension by extending { + externalLocationProviderFactory providing ::JavadocExternalLocationProviderFactory + } + + public val dokkaLocationProvider: Extension by extending { + externalLocationProviderFactory providing ::DefaultExternalLocationProviderFactory + } + + public val fileWriter: Extension by extending { + outputWriter providing ::FileWriter + } + + public val rootCreator: Extension by extending { + htmlPreprocessors with RootCreator applyIf { !delayTemplateSubstitution } + } + + public val defaultSamplesTransformer: Extension by extending { + CoreExtensions.pageTransformer providing ::DefaultSamplesTransformer order { + before(pageMerger) + } + } + + public val sourceLinksTransformer: Extension by extending { + htmlPreprocessors providing ::SourceLinksTransformer order { after(rootCreator) } + } + + public val navigationPageInstaller: Extension by extending { + htmlPreprocessors providing ::NavigationPageInstaller order { after(rootCreator) } + } + + public val scriptsInstaller: Extension by extending { + htmlPreprocessors providing ::ScriptsInstaller order { after(rootCreator) } + } + + public val stylesInstaller: Extension by extending { + htmlPreprocessors providing ::StylesInstaller order { after(rootCreator) } + } + + public val assetsInstaller: Extension by extending { + htmlPreprocessors with AssetsInstaller order { after(rootCreator) } applyIf { !delayTemplateSubstitution } + } + + public val customResourceInstaller: Extension by extending { + htmlPreprocessors providing { ctx -> CustomResourceInstaller(ctx) } order { + after(stylesInstaller) + after(scriptsInstaller) + after(assetsInstaller) + } + } + + public val packageListCreator: Extension by extending { + htmlPreprocessors providing { + PackageListCreator(it, RecognizedLinkFormat.DokkaHtml) + } order { after(rootCreator) } + } + + public val sourcesetDependencyAppender: Extension by extending { + htmlPreprocessors providing ::SourcesetDependencyAppender order { after(rootCreator) } + } + + public val resolveLinkConsumer: Extension by extending { + immediateHtmlCommandConsumer with ResolveLinkConsumer + } + public val replaceVersionConsumer: Extension by extending { + immediateHtmlCommandConsumer providing ::ReplaceVersionsConsumer + } + public val pathToRootConsumer: Extension by extending { + immediateHtmlCommandConsumer with PathToRootConsumer + } + public val baseSearchbarDataInstaller: Extension by extending { + htmlPreprocessors providing ::SearchbarDataInstaller order { after(sourceLinksTransformer) } + } + + // + @Suppress("DEPRECATION_ERROR") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val kotlinAnalysis: ExtensionPoint by extensionPoint() + + @Suppress("DEPRECATION_ERROR") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val externalDocumentablesProvider: ExtensionPoint by extensionPoint() + + @Suppress("DEPRECATION_ERROR") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val externalClasslikesTranslator: ExtensionPoint by extensionPoint() + + @Suppress("DeprecatedCallableAddReplaceWith") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val descriptorToDocumentableTranslator: org.jetbrains.dokka.plugability.Extension + get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError() + + @Suppress("DeprecatedCallableAddReplaceWith") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val psiToDocumentableTranslator: org.jetbrains.dokka.plugability.Extension + get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError() + + @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val defaultKotlinAnalysis: org.jetbrains.dokka.plugability.Extension + get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError() + + @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val defaultExternalDocumentablesProvider: org.jetbrains.dokka.plugability.Extension + get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError() + + @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith") + @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val defaultExternalClasslikesTranslator: org.jetbrains.dokka.plugability.Extension + get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError() + // + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = + PluginApiPreviewAcknowledgement +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBaseConfiguration.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBaseConfiguration.kt new file mode 100644 index 00000000..34195f65 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/DokkaBaseConfiguration.kt @@ -0,0 +1,28 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.base + +import org.jetbrains.dokka.plugability.ConfigurableBlock +import java.io.File +import java.time.Year + +public data class DokkaBaseConfiguration( + var customStyleSheets: List = defaultCustomStyleSheets, + var customAssets: List = defaultCustomAssets, + var separateInheritedMembers: Boolean = separateInheritedMembersDefault, + var footerMessage: String = defaultFooterMessage, + var mergeImplicitExpectActualDeclarations: Boolean = mergeImplicitExpectActualDeclarationsDefault, + var templatesDir: File? = defaultTemplatesDir, + var homepageLink: String? = null, +) : ConfigurableBlock { + public companion object { + public val defaultFooterMessage: String = "© ${Year.now().value} Copyright" + public val defaultCustomStyleSheets: List = emptyList() + public val defaultCustomAssets: List = emptyList() + public const val separateInheritedMembersDefault: Boolean = false + public const val mergeImplicitExpectActualDeclarationsDefault: Boolean = false + public val defaultTemplatesDir: File? = null + } +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/AnalysisApiDeprecatedError.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/AnalysisApiDeprecatedError.kt new file mode 100644 index 00000000..52280b3e --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/AnalysisApiDeprecatedError.kt @@ -0,0 +1,16 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.base.deprecated + +import org.jetbrains.dokka.InternalDokkaApi + +// TODO all API that mentions this message or error can be removed in Dokka >= 2.1 + +internal const val ANALYSIS_API_DEPRECATION_MESSAGE = + "Dokka's Analysis API has been reworked. Please, see the following issue for details and migration options: " + + "https://github.com/Kotlin/dokka/issues/3099" + +@InternalDokkaApi +public class AnalysisApiDeprecatedError : Error(ANALYSIS_API_DEPRECATION_MESSAGE) diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/KotlinAnalysisDeprecatedApi.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/KotlinAnalysisDeprecatedApi.kt new file mode 100644 index 00000000..1d9e7e9f --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/KotlinAnalysisDeprecatedApi.kt @@ -0,0 +1,77 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("PackageDirectoryMismatch", "FunctionName", "UNUSED_PARAMETER", "unused", "DEPRECATION_ERROR", + "DeprecatedCallableAddReplaceWith", "unused" +) + +package org.jetbrains.dokka.analysis + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.DokkaSourceSetID +import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE +import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.utilities.DokkaLogger +import java.io.Closeable + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public abstract class KotlinAnalysis( + private val parent: KotlinAnalysis? = null +) : Closeable { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public operator fun get(key: DokkaConfiguration.DokkaSourceSet): AnalysisContext = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public operator fun get(key: DokkaSourceSetID): AnalysisContext = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + protected abstract fun find(sourceSetID: DokkaSourceSetID): AnalysisContext? +} + +public class AnalysisContext(environment: Any, facade: Any, private val analysisEnvironment: Any) : Closeable { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val environment: Any get() = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public val facade: Any get() = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public operator fun component1(): Any = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public operator fun component2(): Any = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + override fun close() { throw AnalysisApiDeprecatedError() } +} + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public class DokkaAnalysisConfiguration(public val ignoreCommonBuiltIns: Boolean = false) + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun KotlinAnalysis(context: DokkaContext): KotlinAnalysis = throw AnalysisApiDeprecatedError() + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun KotlinAnalysis( + sourceSets: List, + logger: DokkaLogger, + analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration() +): KotlinAnalysis = throw AnalysisApiDeprecatedError() + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun ProjectKotlinAnalysis( + sourceSets: List, + logger: DokkaLogger, + analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration() +): KotlinAnalysis = throw AnalysisApiDeprecatedError() + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun SamplesKotlinAnalysis( + sourceSets: List, + logger: DokkaLogger, + projectKotlinAnalysis: KotlinAnalysis, + analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration() +): KotlinAnalysis = throw AnalysisApiDeprecatedError() + diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersDeprecatedAPI.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersDeprecatedAPI.kt new file mode 100644 index 00000000..55b1daab --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersDeprecatedAPI.kt @@ -0,0 +1,42 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("PackageDirectoryMismatch", "DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith", "unused") + +package org.jetbrains.dokka.base.parsers + +import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE +import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.doc.DocTag +import org.jetbrains.dokka.model.doc.DocumentationNode +import org.jetbrains.dokka.model.doc.TagWrapper + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public abstract class Parser { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public open fun parseStringToDocNode(extractedString: String): DocTag = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public open fun preparse(text: String): String = throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public open fun parseTagWithBody(tagName: String, content: String): TagWrapper = throw AnalysisApiDeprecatedError() +} + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public open class MarkdownParser( + private val externalDri: (String) -> DRI?, + private val kdocLocation: String?, +) : Parser() { + public companion object { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public fun parseFromKDocTag( + @Suppress("UNUSED_PARAMETER") kDocTag: Any?, + @Suppress("UNUSED_PARAMETER") externalDri: (String) -> DRI?, + @Suppress("UNUSED_PARAMETER") kdocLocation: String?, + @Suppress("UNUSED_PARAMETER") parseWithChildren: Boolean = true + ): DocumentationNode = throw AnalysisApiDeprecatedError() + } +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersFactoriesDeprecatedAPI.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersFactoriesDeprecatedAPI.kt new file mode 100644 index 00000000..7b84803c --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/ParsersFactoriesDeprecatedAPI.kt @@ -0,0 +1,24 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("DeprecatedCallableAddReplaceWith", "PackageDirectoryMismatch", "unused") + +package org.jetbrains.dokka.base.parsers.factories + +import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE +import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.doc.DocTag + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public object DocTagsFromStringFactory { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public fun getInstance( + @Suppress("UNUSED_PARAMETER") name: String, + @Suppress("UNUSED_PARAMETER") children: List = emptyList(), + @Suppress("UNUSED_PARAMETER") params: Map = emptyMap(), + @Suppress("UNUSED_PARAMETER") body: String? = null, + @Suppress("UNUSED_PARAMETER") dri: DRI? = null, + ): DocTag = throw AnalysisApiDeprecatedError() +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorDescriptorsDeprecatedAPI.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorDescriptorsDeprecatedAPI.kt new file mode 100644 index 00000000..87d82ccf --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorDescriptorsDeprecatedAPI.kt @@ -0,0 +1,50 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("PackageDirectoryMismatch", "DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith", "unused") + +package org.jetbrains.dokka.base.translators.descriptors + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE +import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DClasslike +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun interface ExternalDocumentablesProvider { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike? +} + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public class DefaultExternalDocumentablesProvider( + @Suppress("UNUSED_PARAMETER") context: DokkaContext +) : ExternalDocumentablesProvider { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + override fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike = + throw AnalysisApiDeprecatedError() +} + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public fun interface ExternalClasslikesTranslator { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + public fun translateClassDescriptor(descriptor: Any, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike +} + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public class DefaultDescriptorToDocumentableTranslator( + private val context: DokkaContext +) : AsyncSourceToDocumentableTranslator, ExternalClasslikesTranslator { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + override suspend fun invokeSuspending(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext, ): DModule = + throw AnalysisApiDeprecatedError() + + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + override fun translateClassDescriptor(descriptor: Any, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike = + throw AnalysisApiDeprecatedError() +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorPsiDeprecatedAPI.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorPsiDeprecatedAPI.kt new file mode 100644 index 00000000..1906a7b1 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/deprecated/TranslatorPsiDeprecatedAPI.kt @@ -0,0 +1,25 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("PackageDirectoryMismatch", "DeprecatedCallableAddReplaceWith", "unused") + +package org.jetbrains.dokka.base.translators.psi + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE +import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator + +@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) +public class DefaultPsiToDocumentableTranslator( + @Suppress("UNUSED_PARAMETER") context: DokkaContext, +) : AsyncSourceToDocumentableTranslator { + @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR) + override suspend fun invokeSuspending( + sourceSet: DokkaConfiguration.DokkaSourceSet, + context: DokkaContext, + ): DModule = throw AnalysisApiDeprecatedError() +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/generation/SingleModuleGeneration.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/generation/SingleModuleGeneration.kt new file mode 100644 index 00000000..8ea109b9 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/generation/SingleModuleGeneration.kt @@ -0,0 +1,131 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.base.generation + +import kotlinx.coroutines.* +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.DokkaException +import org.jetbrains.dokka.Timer +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.generation.Generation +import org.jetbrains.dokka.generation.exitGenerationGracefully +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.pages.RootPageNode +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.query +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator +import org.jetbrains.dokka.utilities.parallelMap +import org.jetbrains.dokka.utilities.report + +public class SingleModuleGeneration(private val context: DokkaContext) : Generation { + + override fun Timer.generate() { + report("Validity check") + validityCheck(context) + + // Step 1: translate sources into documentables & transform documentables (change internally) + report("Creating documentation models") + val modulesFromPlatforms = createDocumentationModels() + + report("Transforming documentation model before merging") + val transformedDocumentationBeforeMerge = transformDocumentationModelBeforeMerge(modulesFromPlatforms) + + report("Merging documentation models") + val transformedDocumentationAfterMerge = mergeDocumentationModels(transformedDocumentationBeforeMerge) + ?: exitGenerationGracefully("Nothing to document") + + report("Transforming documentation model after merging") + val transformedDocumentation = transformDocumentationModelAfterMerge(transformedDocumentationAfterMerge) + + // Step 2: Generate pages & transform them (change internally) + report("Creating pages") + val pages = createPages(transformedDocumentation) + + report("Transforming pages") + val transformedPages = transformPages(pages) + + // Step 3: Rendering + report("Rendering") + render(transformedPages) + + report("Running post-actions") + runPostActions() + + reportAfterRendering() + } + + override val generationName: String = "documentation for ${context.configuration.moduleName}" + + /** + * Implementation note: it runs in a separated single thread due to existing support of coroutines (see #2936) + */ + @OptIn(DelicateCoroutinesApi::class, ExperimentalCoroutinesApi::class) + public fun createDocumentationModels(): List = newSingleThreadContext("Generating documentable model").use { coroutineContext -> // see https://github.com/Kotlin/dokka/issues/3151 + runBlocking(coroutineContext) { + context.configuration.sourceSets.parallelMap { sourceSet -> translateSources(sourceSet, context) }.flatten() + .also { modules -> if (modules.isEmpty()) exitGenerationGracefully("Nothing to document") } + } + } + + + public fun transformDocumentationModelBeforeMerge(modulesFromPlatforms: List): List { + return context.plugin() + .query { preMergeDocumentableTransformer } + .fold(modulesFromPlatforms) { acc, t -> t(acc) } + } + + public fun mergeDocumentationModels(modulesFromPlatforms: List): DModule? = + context.single(CoreExtensions.documentableMerger).invoke(modulesFromPlatforms) + + public fun transformDocumentationModelAfterMerge(documentationModel: DModule): DModule = + context[CoreExtensions.documentableTransformer].fold(documentationModel) { acc, t -> t(acc, context) } + + public fun createPages(transformedDocumentation: DModule): RootPageNode = + context.single(CoreExtensions.documentableToPageTranslator).invoke(transformedDocumentation) + + public fun transformPages(pages: RootPageNode): RootPageNode = + context[CoreExtensions.pageTransformer].fold(pages) { acc, t -> t(acc) } + + public fun render(transformedPages: RootPageNode) { + context.single(CoreExtensions.renderer).render(transformedPages) + } + + public fun runPostActions() { + context[CoreExtensions.postActions].forEach { it() } + } + + public fun validityCheck(context: DokkaContext) { + val (preGenerationCheckResult, checkMessages) = context[CoreExtensions.preGenerationCheck].fold( + Pair(true, emptyList()) + ) { acc, checker -> checker() + acc } + if (!preGenerationCheckResult) throw DokkaException( + "Pre-generation validity check failed: ${checkMessages.joinToString(",")}" + ) + } + + public fun reportAfterRendering() { + context.unusedPoints.takeIf { it.isNotEmpty() }?.also { + context.logger.info("Unused extension points found: ${it.joinToString(", ")}") + } + + context.logger.report() + + if (context.configuration.failOnWarning && (context.logger.warningsCount > 0 || context.logger.errorsCount > 0)) { + throw DokkaException( + "Failed with warningCount=${context.logger.warningsCount} and errorCount=${context.logger.errorsCount}" + ) + } + } + + private suspend fun translateSources(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext) = + context[CoreExtensions.sourceToDocumentableTranslator].parallelMap { translator -> + when (translator) { + is AsyncSourceToDocumentableTranslator -> translator.invokeSuspending(sourceSet, context) + else -> translator.invoke(sourceSet, context) + } + } +} diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/DefaultRenderer.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/DefaultRenderer.kt new file mode 100644 index 00000000..eed7794e --- /dev/null +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/DefaultRenderer.kt @@ -0,0 +1,257 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.base.renderers + +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.coroutineScope +import kotlinx.coroutines.launch +import kotlinx.coroutines.runBlocking +import org.jetbrains.dokka.DokkaException +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.resolvers.local.LocationProvider +import org.jetbrains.dokka.model.DisplaySourceSet +import org.jetbrains.dokka.pages.* +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.renderers.Renderer +import org.jetbrains.dokka.transformers.pages.PageTransformer + +public abstract class DefaultRenderer( + protected val context: DokkaContext +) : Renderer { + + protected val outputWriter: OutputWriter = context.plugin().querySingle { outputWriter } + + protected lateinit var locationProvider: LocationProvider + private set + + protected open val preprocessors: Iterable = emptyList() + + public abstract fun T.buildHeader(level: Int, node: ContentHeader, content: T.() -> Unit) + public abstract fun T.buildLink(address: String, content: T.() -> Unit) + public abstract fun T.buildList( + node: ContentList, + pageContext: ContentPage, + sourceSetRestriction: Set? = null + ) + + public abstract fun T.buildLineBreak() + public open fun T.buildLineBreak(node: ContentBreakLine, pageContext: ContentPage) { + buildLineBreak() + } + + public abstract fun T.buildResource(node: ContentEmbeddedResource, pageContext: ContentPage) + public abstract fun T.buildTable( + node: ContentTable, + pageContext: ContentPage, + sourceSetRestriction: Set? = null + ) + + public abstract fun T.buildText(textNode: ContentText) + public abstract fun T.buildNavigation(page: PageNode) + + public abstract fun buildPage(page: ContentPage, content: (T, ContentPage) -> Unit): String + public abstract fun buildError(node: ContentNode) + + public open fun T.buildPlatformDependent( + content: PlatformHintedContent, + pageContext: ContentPage, + sourceSetRestriction: Set? + ) { + buildContentNode(content.inner, pageContext) + } + + public open fun T.buildGroup( + node: ContentGroup, + pageContext: ContentPage, + sourceSetRestriction: Set? = null + ) { + wrapGroup(node, pageContext) { node.children.forEach { it.build(this, pageContext, sourceSetRestriction) } } + } + + public open fun T.buildDivergent(node: ContentDivergentGroup, pageContext: ContentPage) { + node.children.forEach { it.build(this, pageContext) } + } + + public open fun T.wrapGroup(node: ContentGroup, pageContext: ContentPage, childrenCallback: T.() -> Unit) { + childrenCallback() + } + + public open fun T.buildText( + nodes: List, + pageContext: C