diff options
Diffstat (limited to 'dokka-runners/runner-maven-plugin')
10 files changed, 1258 insertions, 0 deletions
diff --git a/dokka-runners/runner-maven-plugin/api/runner-maven-plugin.api b/dokka-runners/runner-maven-plugin/api/runner-maven-plugin.api new file mode 100644 index 00000000..069e7744 --- /dev/null +++ b/dokka-runners/runner-maven-plugin/api/runner-maven-plugin.api @@ -0,0 +1,141 @@ +public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/maven/plugin/AbstractMojo { + public fun <init> (Ljava/util/List;)V + public fun execute ()V + public final fun getApiVersion ()Ljava/lang/String; + public final fun getCacheRoot ()Ljava/lang/String; + public final fun getClasspath ()Ljava/util/List; + public final fun getDisplayName ()Ljava/lang/String; + public final fun getDocumentedVisibilities ()Ljava/util/Set; + public final fun getDokkaPlugins ()Ljava/util/List; + public final fun getExternalDocumentationLinks ()Ljava/util/List; + public final fun getFailOnWarning ()Z + public final fun getIncludeNonPublic ()Z + public final fun getIncludes ()Ljava/util/List; + public final fun getJdkVersion ()I + public final fun getLanguageVersion ()Ljava/lang/String; + protected final fun getMavenProject ()Lorg/apache/maven/project/MavenProject; + public final fun getModuleName ()Ljava/lang/String; + public final fun getNoJdkLink ()Z + public final fun getNoStdlibLink ()Z + public final fun getOfflineMode ()Z + protected abstract fun getOutDir ()Ljava/lang/String; + public final fun getPerPackageOptions ()Ljava/util/List; + public final fun getPlatform ()Ljava/lang/String; + public final fun getReportUndocumented ()Z + public final fun getSamples ()Ljava/util/List; + protected final fun getSession ()Lorg/apache/maven/execution/MavenSession; + public final fun getSkip ()Z + public final fun getSkipDeprecated ()Z + public final fun getSkipEmptyPackages ()Z + public final fun getSourceDirectories ()Ljava/util/List; + public final fun getSourceLinks ()Ljava/util/List; + public final fun getSourceSetName ()Ljava/lang/String; + public final fun getSuppressInheritedMembers ()Z + public final fun getSuppressObviousFunctions ()Z + public final fun getSuppressedFiles ()Ljava/util/List; + public final fun setApiVersion (Ljava/lang/String;)V + public final fun setCacheRoot (Ljava/lang/String;)V + public final fun setClasspath (Ljava/util/List;)V + public final fun setDisplayName (Ljava/lang/String;)V + public final fun setDocumentedVisibilities (Ljava/util/Set;)V + public final fun setDokkaPlugins (Ljava/util/List;)V + public final fun setExternalDocumentationLinks (Ljava/util/List;)V + public final fun setFailOnWarning (Z)V + public final fun setIncludeNonPublic (Z)V + public final fun setIncludes (Ljava/util/List;)V + public final fun setJdkVersion (I)V + public final fun setLanguageVersion (Ljava/lang/String;)V + protected final fun setMavenProject (Lorg/apache/maven/project/MavenProject;)V + public final fun setModuleName (Ljava/lang/String;)V + public final fun setNoJdkLink (Z)V + public final fun setNoStdlibLink (Z)V + public final fun setOfflineMode (Z)V + public final fun setPerPackageOptions (Ljava/util/List;)V + public final fun setPlatform (Ljava/lang/String;)V + public final fun setReportUndocumented (Z)V + public final fun setSamples (Ljava/util/List;)V + protected final fun setSession (Lorg/apache/maven/execution/MavenSession;)V + public final fun setSkip (Z)V + public final fun setSkipDeprecated (Z)V + public final fun setSkipEmptyPackages (Z)V + public final fun setSourceDirectories (Ljava/util/List;)V + public final fun setSourceLinks (Ljava/util/List;)V + public final fun setSourceSetName (Ljava/lang/String;)V + public final fun setSuppressInheritedMembers (Z)V + public final fun setSuppressObviousFunctions (Z)V + public final fun setSuppressedFiles (Ljava/util/List;)V +} + +public final class org/jetbrains/dokka/maven/DokkaJavadocJarMojo : org/jetbrains/dokka/maven/AbstractDokkaMojo { + public fun <init> ()V + public fun execute ()V + public final fun getOutputDir ()Ljava/lang/String; + public final fun setOutputDir (Ljava/lang/String;)V +} + +public final class org/jetbrains/dokka/maven/DokkaJavadocMojo : org/jetbrains/dokka/maven/AbstractDokkaMojo { + public fun <init> ()V + public final fun getOutputDir ()Ljava/lang/String; + public final fun setOutputDir (Ljava/lang/String;)V +} + +public final class org/jetbrains/dokka/maven/DokkaMojo : org/jetbrains/dokka/maven/AbstractDokkaMojo { + public fun <init> ()V + public final fun getOutputDir ()Ljava/lang/String; + public final fun setOutputDir (Ljava/lang/String;)V +} + +public final class org/jetbrains/dokka/maven/ExternalDocumentationLinkBuilder { + public fun <init> ()V + public final fun build ()Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl; + public final fun getPackageListUrl ()Ljava/net/URL; + public final fun getUrl ()Ljava/net/URL; + public final fun setPackageListUrl (Ljava/net/URL;)V + public final fun setUrl (Ljava/net/URL;)V +} + +public class org/jetbrains/dokka/maven/HelpMojo : org/apache/maven/plugin/AbstractMojo { + public fun <init> ()V + public fun execute ()V +} + +public final class org/jetbrains/dokka/maven/MavenDokkaLogger : org/jetbrains/dokka/utilities/DokkaLogger { + public fun <init> (Lorg/apache/maven/plugin/logging/Log;)V + public fun debug (Ljava/lang/String;)V + public fun error (Ljava/lang/String;)V + public fun getErrorsCount ()I + public final fun getLog ()Lorg/apache/maven/plugin/logging/Log; + public fun getWarningsCount ()I + public fun info (Ljava/lang/String;)V + public fun progress (Ljava/lang/String;)V + public fun setErrorsCount (I)V + public fun setWarningsCount (I)V + public fun warn (Ljava/lang/String;)V +} + +public final class org/jetbrains/dokka/maven/PackageOptions : org/jetbrains/dokka/DokkaConfiguration$PackageOptions { + public fun <init> ()V + public fun getDocumentedVisibilities ()Ljava/util/Set; + public fun getIncludeNonPublic ()Z + public fun getMatchingRegex ()Ljava/lang/String; + public fun getReportUndocumented ()Ljava/lang/Boolean; + public fun getSkipDeprecated ()Z + public fun getSuppress ()Z + public fun setDocumentedVisibilities (Ljava/util/Set;)V + public fun setIncludeNonPublic (Z)V + public fun setMatchingRegex (Ljava/lang/String;)V + public fun setReportUndocumented (Z)V + public fun setSkipDeprecated (Z)V + public fun setSuppress (Z)V +} + +public final class org/jetbrains/dokka/maven/SourceLinkMapItem { + public fun <init> ()V + public final fun getLineSuffix ()Ljava/lang/String; + public final fun getPath ()Ljava/lang/String; + public final fun getUrl ()Ljava/lang/String; + public final fun setLineSuffix (Ljava/lang/String;)V + public final fun setPath (Ljava/lang/String;)V + public final fun setUrl (Ljava/lang/String;)V +} + diff --git a/dokka-runners/runner-maven-plugin/build.gradle.kts b/dokka-runners/runner-maven-plugin/build.gradle.kts new file mode 100644 index 00000000..f0de8dd5 --- /dev/null +++ b/dokka-runners/runner-maven-plugin/build.gradle.kts @@ -0,0 +1,137 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +import dokkabuild.overridePublicationArtifactId + +plugins { + id("dokkabuild.kotlin-jvm") + id("dokkabuild.publish-jvm") + id("dokkabuild.setup-maven-cli") + alias(libs.plugins.kotlinx.binaryCompatibilityValidator) +} + +overridePublicationArtifactId("dokka-maven-plugin") + +dependencies { + // this version is required, so that it will be available in the POM of plugin + implementation("org.jetbrains.dokka:dokka-core:$version") + + implementation(libs.apacheMaven.core) + implementation(libs.apacheMaven.pluginApi) + implementation(libs.apacheMaven.pluginAnnotations) + implementation(libs.apacheMaven.archiver) +} + +val mavenPluginTaskGroup = "maven plugin" + +val generatePom by tasks.registering(Sync::class) { + description = "Generate pom.xml for Maven Plugin Plugin" + group = mavenPluginTaskGroup + + inputs.property("dokka_version", project.version) + + val pomTemplateFile = layout.projectDirectory.file("pom.template.xml") + + val mavenVersion = mavenCliSetup.mavenVersion.orNull + val mavenPluginToolsVersion = mavenCliSetup.mavenPluginToolsVersion.orNull + + from(pomTemplateFile) { + rename { it.replace(".template.xml", ".xml") } + + expand( + "mavenVersion" to mavenVersion, + "dokka_version" to project.version, + "mavenPluginToolsVersion" to mavenPluginToolsVersion, + ) + } + + into(temporaryDir) +} + +val prepareHelpMojoDir by tasks.registering(Sync::class) { + description = "Prepare files for generating the Maven Plugin HelpMojo" + group = mavenPluginTaskGroup + + into(layout.buildDirectory.dir("maven-help-mojo")) + from(generatePom) +} + +val helpMojo by tasks.registering(Exec::class) { + description = "Generate the Maven Plugin HelpMojo" + group = mavenPluginTaskGroup + + dependsOn(tasks.installMavenBinary, prepareHelpMojoDir) + + workingDir(prepareHelpMojoDir.map { it.destinationDir }) + executable(mavenCliSetup.mvn.get()) + args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:helpmojo") + + outputs.dir(workingDir) +} + +val helpMojoSources by tasks.registering(Sync::class) { + description = "Sync the HelpMojo source files into a SourceSet SrcDir" + group = mavenPluginTaskGroup + from(helpMojo) { + eachFile { + // drop 2 leading directories + relativePath = RelativePath(true, *relativePath.segments.drop(2).toTypedArray()) + } + } + includeEmptyDirs = false + into(temporaryDir) + include("**/*.java") +} + +val helpMojoResources by tasks.registering(Sync::class) { + description = "Sync the HelpMojo resource files into a SourceSet SrcDir" + group = mavenPluginTaskGroup + from(helpMojo) + into(temporaryDir) + include("**/**") + exclude("**/*.java") +} + +sourceSets.main { + // use the generated HelpMojo as compilation input, so Gradle will automatically generate the mojo + java.srcDirs(helpMojoSources) + resources.srcDirs(helpMojoResources) +} + +val preparePluginDescriptorDir by tasks.registering(Sync::class) { + description = "Prepare files for generating the Maven Plugin descriptor" + group = mavenPluginTaskGroup + + into(layout.buildDirectory.dir("maven-plugin-descriptor")) + + from(tasks.compileKotlin) { into("classes/java/main") } + from(tasks.compileJava) { into("classes/java/main") } + from(helpMojoResources) +} + +val pluginDescriptor by tasks.registering(Exec::class) { + description = "Generate the Maven Plugin descriptor" + group = mavenPluginTaskGroup + + dependsOn(tasks.installMavenBinary, preparePluginDescriptorDir) + + workingDir(preparePluginDescriptorDir.map { it.destinationDir }) + executable(mavenCliSetup.mvn.get()) + args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:descriptor") + + outputs.dir("$workingDir/classes/java/main/META-INF/maven") +} + +tasks.jar { + metaInf { + from(pluginDescriptor) { + into("maven") + } + } + manifest { + attributes("Class-Path" to configurations.runtimeClasspath.map { configuration -> + configuration.resolve().joinToString(" ") { it.name } + }) + } +} diff --git a/dokka-runners/runner-maven-plugin/gradle.properties b/dokka-runners/runner-maven-plugin/gradle.properties new file mode 100644 index 00000000..5715ee14 --- /dev/null +++ b/dokka-runners/runner-maven-plugin/gradle.properties @@ -0,0 +1,9 @@ +# +# Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. +# +group=org.jetbrains.dokka +version=1.9.20-SNAPSHOT + +org.jetbrains.dokka.javaToolchain.mainCompiler=8 +org.jetbrains.dokka.javaToolchain.testLauncher=8 +org.jetbrains.dokka.kotlinLanguageLevel=1.4 diff --git a/dokka-runners/runner-maven-plugin/pom.template.xml b/dokka-runners/runner-maven-plugin/pom.template.xml new file mode 100644 index 00000000..b4795112 --- /dev/null +++ b/dokka-runners/runner-maven-plugin/pom.template.xml @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + --> + +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>dokka-maven-plugin</artifactId> + <version>${dokka_version}</version> + <packaging>maven-plugin</packaging> + <properties> + <maven.version>${mavenVersion}</maven.version> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> + </properties> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-plugin-plugin</artifactId> + <version>${mavenPluginToolsVersion}</version> + <configuration> + <helpPackageName>org.jetbrains.dokka.maven</helpPackageName> + <skipErrorNoDescriptorsFound>true</skipErrorNoDescriptorsFound> + </configuration> + <executions> + <execution> + <id>default-descriptor</id> + <goals> + <goal>descriptor</goal> + </goals> + <phase>process-classes</phase> + </execution> + <execution> + <id>help-descriptor</id> + <goals> + <goal>helpmojo</goal> + </goals> + <phase>process-classes</phase> + </execution> + </executions> + </plugin> + </plugins> + <directory>./</directory> + <outputDirectory>./classes/java/main</outputDirectory> + </build> + <dependencies> + <dependency> + <groupId>org.apache.maven.plugin-tools</groupId> + <artifactId>maven-plugin-annotations</artifactId> + <version>${mavenPluginToolsVersion}</version> + <scope>provided</scope> + </dependency> + </dependencies> +</project> diff --git a/dokka-runners/runner-maven-plugin/settings.gradle.kts b/dokka-runners/runner-maven-plugin/settings.gradle.kts new file mode 100644 index 00000000..63bf3743 --- /dev/null +++ b/dokka-runners/runner-maven-plugin/settings.gradle.kts @@ -0,0 +1,30 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +@file:Suppress("UnstableApiUsage") + +rootProject.name = "runner-maven-plugin" + +pluginManagement { + includeBuild("../../build-logic") + + repositories { + mavenCentral() + gradlePluginPortal() + } +} + +dependencyResolutionManagement { + repositories { + mavenCentral() + } + + versionCatalogs { + create("libs") { + from(files("../../gradle/libs.versions.toml")) + } + } +} + +enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") diff --git a/dokka-runners/runner-maven-plugin/src/main/kotlin/org/jetbrains/dokka/maven/DokkaMojo.kt b/dokka-runners/runner-maven-plugin/src/main/kotlin/org/jetbrains/dokka/maven/DokkaMojo.kt new file mode 100644 index 00000000..d14fea9c --- /dev/null +++ b/dokka-runners/runner-maven-plugin/src/main/kotlin/org/jetbrains/dokka/maven/DokkaMojo.kt @@ -0,0 +1,615 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.maven + +import org.apache.maven.archiver.MavenArchiveConfiguration +import org.apache.maven.archiver.MavenArchiver +import org.apache.maven.artifact.DefaultArtifact +import org.apache.maven.artifact.handler.DefaultArtifactHandler +import org.apache.maven.artifact.resolver.ArtifactResolutionRequest +import org.apache.maven.artifact.resolver.ArtifactResolutionResult +import org.apache.maven.artifact.resolver.ResolutionErrorHandler +import org.apache.maven.execution.MavenSession +import org.apache.maven.model.Dependency +import org.apache.maven.plugin.AbstractMojo +import org.apache.maven.plugin.MojoExecutionException +import org.apache.maven.plugins.annotations.* +import org.apache.maven.project.MavenProject +import org.apache.maven.project.MavenProjectHelper +import org.apache.maven.repository.RepositorySystem +import org.codehaus.plexus.archiver.Archiver +import org.codehaus.plexus.archiver.jar.JarArchiver +import org.codehaus.plexus.archiver.util.DefaultFileSet +import org.codehaus.plexus.util.xml.Xpp3Dom +import org.jetbrains.dokka.* +import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink +import java.io.File +import java.net.URL + +public abstract class AbstractDokkaMojo( + private val defaultDokkaPlugins: List<Dependency> +) : AbstractMojo() { + + @Parameter(defaultValue = "\${project}", readonly = true, required = true) + protected var mavenProject: MavenProject? = null + + /** + * The current build session instance. This is used for + * dependency resolver API calls via repositorySystem. + */ + @Parameter(defaultValue = "\${session}", required = true, readonly = true) + protected var session: MavenSession? = null + + @Component + private var repositorySystem: RepositorySystem? = null + + @Component + private var resolutionErrorHandler: ResolutionErrorHandler? = null + + @Parameter(defaultValue = "JVM") + public var displayName: String = "JVM" + + @Parameter + public var sourceSetName: String = "JVM" + + /** + * Source code roots to be analyzed and documented. + * Accepts directories and individual `.kt` / `.java` files. + * + * Default is `{project.compileSourceRoots}`. + */ + @Parameter(required = true, defaultValue = "\${project.compileSourceRoots}") + public var sourceDirectories: List<String> = emptyList() + + /** + * List of directories or files that contain sample functions which are referenced via + * [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) KDoc tag. + */ + @Parameter + public var samples: List<String> = emptyList() + + /** + * List of Markdown files that contain + * [module and package documentation](https://kotlinlang.org/docs/dokka-module-and-package-docs.html). + * + * Contents of specified files will be parsed and embedded into documentation as module and package descriptions. + * + * Example of such a file: + * + * ```markdown + * # Module kotlin-demo + * + * The module shows the Dokka usage. + * + * # Package org.jetbrains.kotlin.demo + * + * Contains assorted useful stuff. + * + * ## Level 2 heading + * + * Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo` + * + * # Package org.jetbrains.kotlin.demo2 + * + * Useful stuff in another package. + * ``` + */ + @Parameter + public var includes: List<String> = emptyList() + + /** + * Classpath for analysis and interactive samples. + * + * Useful if some types that come from dependencies are not resolved/picked up automatically. + * Property accepts both `.jar` and `.klib` files. + * + * Default is `{project.compileClasspathElements}`. + */ + @Parameter(required = true, defaultValue = "\${project.compileClasspathElements}") + public var classpath: List<String> = emptyList() + + /** + * Specifies the location of the project source code on the Web. If provided, Dokka generates + * "source" links for each declaration. See [SourceLinkMapItem] for more details. + */ + @Parameter + public var sourceLinks: List<SourceLinkMapItem> = emptyList() + + /** + * Display name used to refer to the project/module. Used for ToC, navigation, logging, etc. + * + * Default is `{project.artifactId}`. + */ + @Parameter(required = true, defaultValue = "\${project.artifactId}") + public var moduleName: String = "" + + /** + * Whether to skip documentation generation. + * + * Default is `false`. + */ + @Parameter(required = false, defaultValue = "false") + public var skip: Boolean = false + + /** + * JDK version to use when generating external documentation links for Java types. + * + * For instance, if you use [java.util.UUID] from JDK in some public declaration signature, + * and this property is set to `8`, Dokka will generate an external documentation link + * to [JDK 8 Javadocs](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html) for it. + * + * Default is JDK 8. + */ + @Parameter(required = false, defaultValue = "${DokkaDefaults.jdkVersion}") + public var jdkVersion: Int = DokkaDefaults.jdkVersion + + /** + * Whether to document declarations annotated with [Deprecated]. + * + * Can be overridden on package level by setting [PackageOptions.skipDeprecated]. + * + * Default is `false`. + */ + @Parameter + public var skipDeprecated: Boolean = DokkaDefaults.skipDeprecated + + /** + * Whether to skip packages that contain no visible declarations after + * various filters have been applied. + * + * For instance, if [skipDeprecated] is set to `true` and your package contains only + * deprecated declarations, it will be considered to be empty. + * + * Default is `true`. + */ + @Parameter + public var skipEmptyPackages: Boolean = DokkaDefaults.skipEmptyPackages + + /** + * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + * after they have been filtered by [documentedVisibilities]. + * + * This setting works well with [failOnWarning]. + * + * Can be overridden for a specific package by setting [PackageOptions.reportUndocumented]. + * + * Default is `false`. + */ + @Parameter + public var reportUndocumented: Boolean = DokkaDefaults.reportUndocumented + + /** + * Allows to customize documentation generation options on a per-package basis. + * + * @see PackageOptions for details + */ + @Parameter + public var perPackageOptions: List<PackageOptions> = emptyList() + + /** + * Allows linking to Dokka/Javadoc documentation of the project's dependencies. + * + * @see ExternalDocumentationLinkBuilder for details + */ + @Parameter + public var externalDocumentationLinks: List<ExternalDocumentationLinkBuilder> = emptyList() + + /** + * Whether to generate external documentation links that lead to API reference + * documentation for Kotlin's standard library when declarations from it are used. + * + * Default is `false`, meaning links will be generated. + */ + @Parameter(defaultValue = "${DokkaDefaults.noStdlibLink}") + public var noStdlibLink: Boolean = DokkaDefaults.noStdlibLink + + /** + * Whether to generate external documentation links to JDK's Javadocs + * when declarations from it are used. + * + * The version of JDK Javadocs is determined by [jdkVersion] property. + * + * Default is `false`, meaning links will be generated. + */ + @Parameter(defaultValue = "${DokkaDefaults.noJdkLink}") + public var noJdkLink: Boolean = DokkaDefaults.noJdkLink + + /** + * Whether to resolve remote files/links over network. + * + * This includes package-lists used for generating external documentation links: + * for instance, to make classes from standard library clickable. + * + * Setting this to `true` can significantly speed up build times in certain cases, + * but can also worsen documentation quality and user experience, for instance by + * not resolving some dependency's class/member links. + * + * When using offline mode, you can cache fetched files locally and provide them to + * Dokka as local paths. For instance, see [ExternalDocumentationLinkBuilder]. + * + * Default is `false`. + */ + @Parameter(defaultValue = "${DokkaDefaults.offlineMode}") + public var offlineMode: Boolean = DokkaDefaults.offlineMode + + /** + * [Kotlin language version](https://kotlinlang.org/docs/compatibility-modes.html) + * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) + * environment. + * + * By default, the latest language version available to Dokka's embedded compiler will be used. + */ + @Parameter + public var languageVersion: String? = null + + /** + * [Kotlin API version](https://kotlinlang.org/docs/compatibility-modes.html) + * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) + * environment. + * + * By default, it will be deduced from [languageVersion]. + */ + @Parameter + public var apiVersion: String? = null + + /** + * Directories or individual files that should be suppressed, meaning declarations from them + * will be not documented. + */ + @Parameter + public var suppressedFiles: List<String> = emptyList() + + /** + * Set of visibility modifiers that should be documented. + * + * This can be used if you want to document protected/internal/private declarations, + * as well as if you want to exclude public declarations and only document internal API. + * + * Can be configured on per-package basis, see [PackageOptions.documentedVisibilities]. + * + * Default is [DokkaConfiguration.Visibility.PUBLIC]. + */ + @Parameter(property = "visibility") + public var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities + // hack to set the default value for lists, didn't find any other safe way + // maven seems to overwrite Kotlin's default initialization value, so it doesn't matter what you put there + get() = field.ifEmpty { DokkaDefaults.documentedVisibilities } + + /** + * Whether to fail documentation generation if Dokka has emitted a warning or an error. + * Will wait until all errors and warnings have been emitted first. + * + * This setting works well with [reportUndocumented] + * + * Default is `false`. + */ + @Parameter + public var failOnWarning: Boolean = DokkaDefaults.failOnWarning + + /** + * Whether to suppress obvious functions. + * + * A function is considered to be obvious if it is: + * - Inherited from `kotlin.Any`, `Kotlin.Enum`, `java.lang.Object` or `java.lang.Enum`, + * such as `equals`, `hashCode`, `toString`. + * - Synthetic (generated by the compiler) and does not have any documentation, such as + * `dataClass.componentN` or `dataClass.copy`. + * + * Default is `true` + */ + @Parameter(defaultValue = "${DokkaDefaults.suppressObviousFunctions}") + public var suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions + + /** + * Whether to suppress inherited members that aren't explicitly overridden in a given class. + * + * Note: this can suppress functions such as `equals`/`hashCode`/`toString`, but cannot suppress + * synthetic functions such as `dataClass.componentN` and `dataClass.copy`. Use [suppressObviousFunctions] + * for that. + * + * Default is `false`. + */ + @Parameter(defaultValue = "${DokkaDefaults.suppressInheritedMembers}") + public var suppressInheritedMembers: Boolean = DokkaDefaults.suppressInheritedMembers + + /** + * Dokka plugins to be using during documentation generation. + * + * Example: + * + * ```xml + * <dokkaPlugins> + * <plugin> + * <groupId>org.jetbrains.dokka</groupId> + * <artifactId>gfm-plugin</artifactId> + * <version>1.7.20</version> + * </plugin> + * </dokkaPlugins> + * ``` + */ + @Parameter + public var dokkaPlugins: List<Dependency> = emptyList() + get() = field + defaultDokkaPlugins + + @Parameter + public var cacheRoot: String? = null + + @Parameter + public var platform: String = "" + + /** + * Deprecated. Use [documentedVisibilities] instead. + */ + @Parameter + public var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic + + protected abstract fun getOutDir(): String + + override fun execute() { + if (skip) { + log.info("Dokka skip parameter is true so no dokka output will be produced") + return + } + + sourceLinks.forEach { + if (it.path.contains("\\")) { + throw MojoExecutionException("Incorrect path property, only Unix based path allowed.") + } + } + + if (moduleName.contains(',')) { + // To figure out why this is needed and if it is still relevant, see the comment here: + // https://github.com/Kotlin/dokka/issues/3011#issuecomment-1568620493 + throw IllegalArgumentException("Module name cannot contain commas as it is used internally as a delimiter.") + } + + fun defaultLinks(config: DokkaSourceSetImpl): Set<ExternalDocumentationLinkImpl> { + val links = mutableSetOf<ExternalDocumentationLinkImpl>() + if (!config.noJdkLink) + links += ExternalDocumentationLink.jdk(jdkVersion) + + if (!config.noStdlibLink) + links += ExternalDocumentationLink.kotlinStdlib() + return links + } + + val sourceSet = DokkaSourceSetImpl( + displayName = displayName, + sourceSetID = DokkaSourceSetID(moduleName, sourceSetName), + classpath = classpath.map(::File), + sourceRoots = sourceDirectories.map(::File).toSet(), + dependentSourceSets = emptySet(), + samples = samples.map(::File).toSet(), + includes = includes.map(::File).toSet(), + includeNonPublic = includeNonPublic, + documentedVisibilities = documentedVisibilities, + reportUndocumented = reportUndocumented, + skipEmptyPackages = skipEmptyPackages, + skipDeprecated = skipDeprecated, + jdkVersion = jdkVersion, + sourceLinks = sourceLinks.map { SourceLinkDefinitionImpl(File(it.path).canonicalPath, URL(it.url), it.lineSuffix) }.toSet(), + perPackageOptions = perPackageOptions.map { + @Suppress("DEPRECATION") // for includeNonPublic, preserve backwards compatibility + PackageOptionsImpl( + matchingRegex = it.matchingRegex, + includeNonPublic = it.includeNonPublic, + documentedVisibilities = it.documentedVisibilities, + reportUndocumented = it.reportUndocumented, + skipDeprecated = it.skipDeprecated, + suppress = it.suppress + ) + }, + externalDocumentationLinks = externalDocumentationLinks.map { it.build() }.toSet(), + languageVersion = languageVersion, + apiVersion = apiVersion, + noStdlibLink = noStdlibLink, + noJdkLink = noJdkLink, + suppressedFiles = suppressedFiles.map(::File).toSet(), + analysisPlatform = if (platform.isNotEmpty()) Platform.fromString(platform) else Platform.DEFAULT, + ).let { + it.copy( + externalDocumentationLinks = defaultLinks(it) + it.externalDocumentationLinks + ) + } + + val logger = MavenDokkaLogger(log) + + val pluginsConfiguration = + (mavenProject?.getPlugin("org.jetbrains.dokka:dokka-maven-plugin")?.configuration as? Xpp3Dom) + ?.getChild("pluginsConfiguration")?.children?.map { + PluginConfigurationImpl( + it.name, + DokkaConfiguration.SerializationFormat.XML, + it.toString() + ) + }.orEmpty() + + val configuration = DokkaConfigurationImpl( + moduleName = moduleName, + outputDir = File(getOutDir()), + offlineMode = offlineMode, + cacheRoot = cacheRoot?.let(::File), + sourceSets = listOf(sourceSet), + // TODO [beresnev] analysis switcher + pluginsClasspath = getArtifactByMaven("org.jetbrains.dokka", "analysis-kotlin-descriptors", dokkaVersion) + + getArtifactByMaven("org.jetbrains.dokka", "dokka-base", dokkaVersion) + + dokkaPlugins.map { getArtifactByMaven(it.groupId, it.artifactId, it.version ?: dokkaVersion) } + .flatten(), + pluginsConfiguration = pluginsConfiguration.toMutableList(), + modules = emptyList(), + failOnWarning = failOnWarning, + suppressObviousFunctions = suppressObviousFunctions, + suppressInheritedMembers = suppressInheritedMembers, + // looks like maven has different life cycle compared to gradle, + // so finalizing coroutines after each module pass causes an error. + // see https://github.com/Kotlin/dokka/issues/2457 + finalizeCoroutines = false, + ) + + val gen = DokkaGenerator(configuration, logger) + + gen.generate() + } + + private fun getArtifactByMaven( + groupId: String, + artifactId: String, + version: String + ): List<File> { + + val request = ArtifactResolutionRequest().apply { + isResolveRoot = true + isResolveTransitively = true + localRepository = session!!.localRepository + remoteRepositories = mavenProject!!.pluginArtifactRepositories + isOffline = session!!.isOffline + isForceUpdate = session!!.request.isUpdateSnapshots + servers = session!!.request.servers + mirrors = session!!.request.mirrors + proxies = session!!.request.proxies + artifact = DefaultArtifact( + groupId, artifactId, version, "compile", "jar", null, + DefaultArtifactHandler("jar") + ) + } + + log.debug("Resolving $groupId:$artifactId:$version ...") + + val result: ArtifactResolutionResult = repositorySystem!!.resolve(request) + resolutionErrorHandler!!.throwErrors(request, result)</ |