aboutsummaryrefslogtreecommitdiff
path: root/runners/maven-plugin
diff options
context:
space:
mode:
authorIgnat Beresnev <ignat.beresnev@jetbrains.com>2023-11-10 11:46:54 +0100
committerGitHub <noreply@github.com>2023-11-10 11:46:54 +0100
commit8e5c63d035ef44a269b8c43430f43f5c8eebfb63 (patch)
tree1b915207b2b9f61951ddbf0ff2e687efd053d555 /runners/maven-plugin
parenta44efd4ba0c2e4ab921ff75e0f53fc9335aa79db (diff)
downloaddokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.tar.gz
dokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.tar.bz2
dokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.zip
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 <whyoleg@gmail.com>
Diffstat (limited to 'runners/maven-plugin')
-rw-r--r--runners/maven-plugin/api/maven-plugin.api141
-rw-r--r--runners/maven-plugin/build.gradle.kts138
-rw-r--r--runners/maven-plugin/pom.template.xml56
-rw-r--r--runners/maven-plugin/src/main/kotlin/DokkaMojo.kt615
-rw-r--r--runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt68
-rw-r--r--runners/maven-plugin/src/main/kotlin/MavenDokkaLogger.kt44
-rw-r--r--runners/maven-plugin/src/main/kotlin/PackageOptions.kt89
-rw-r--r--runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt69
8 files changed, 0 insertions, 1220 deletions
diff --git a/runners/maven-plugin/api/maven-plugin.api b/runners/maven-plugin/api/maven-plugin.api
deleted file mode 100644
index 069e7744..00000000
--- a/runners/maven-plugin/api/maven-plugin.api
+++ /dev/null
@@ -1,141 +0,0 @@
-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/runners/maven-plugin/build.gradle.kts b/runners/maven-plugin/build.gradle.kts
deleted file mode 100644
index 825493ad..00000000
--- a/runners/maven-plugin/build.gradle.kts
+++ /dev/null
@@ -1,138 +0,0 @@
-/*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-import org.jetbrains.registerDokkaArtifactPublication
-
-plugins {
- id("org.jetbrains.conventions.kotlin-jvm")
- id("org.jetbrains.conventions.maven-publish")
- id("org.jetbrains.conventions.maven-cli-setup")
-}
-
-dependencies {
- implementation(projects.core)
-
- 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
-
- val dokka_version: String by project
- inputs.property("dokka_version", dokka_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 dokka_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 }
- })
- }
-}
-
-registerDokkaArtifactPublication("dokkaMavenPlugin") {
- artifactId = "dokka-maven-plugin"
-}
diff --git a/runners/maven-plugin/pom.template.xml b/runners/maven-plugin/pom.template.xml
deleted file mode 100644
index b4795112..00000000
--- a/runners/maven-plugin/pom.template.xml
+++ /dev/null
@@ -1,56 +0,0 @@
-<?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/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt
deleted file mode 100644
index d14fea9c..00000000
--- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt
+++ /dev/null
@@ -1,615 +0,0 @@
-/*
- * 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)
- return result.artifacts.map { it.file }
- }
-
- private val dokkaVersion: String by lazy {
- mavenProject?.pluginArtifacts?.firstOrNull { it.groupId == "org.jetbrains.dokka" && it.artifactId == "dokka-maven-plugin" }?.version
- ?: throw IllegalStateException("Not found dokka plugin")
- }
-}
-
-@Mojo(
- name = "dokka",
- defaultPhase = LifecyclePhase.PRE_SITE,
- threadSafe = true,
- requiresDependencyResolution = ResolutionScope.COMPILE,
- requiresProject = true
-)
-public class DokkaMojo : AbstractDokkaMojo(emptyList()) {
-
- /**
- * Directory to which documentation will be generated.
- *
- * Default is `{project.basedir}/target/dokka`.
- */
- @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokka")
- public var outputDir: String = ""
-
- override fun getOutDir(): String = outputDir
-}
-
-@Mojo(
- name = "javadoc",
- defaultPhase = LifecyclePhase.PRE_SITE,
- threadSafe = true,
- requiresDependencyResolution = ResolutionScope.COMPILE,
- requiresProject = true
-)
-public class DokkaJavadocMojo : AbstractDokkaMojo(listOf(javadocDependency)) {
-
- /**
- * Directory to which documentation will be generated.
- *
- * Default is `{project.basedir}/target/dokkaJavadoc`.
- */
- @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokkaJavadoc")
- public var outputDir: String = ""
-
- override fun getOutDir(): String = outputDir
-}
-
-@Mojo(
- name = "javadocJar",
- defaultPhase = LifecyclePhase.PRE_SITE,
- threadSafe = true,
- requiresDependencyResolution = ResolutionScope.COMPILE,
- requiresProject = true
-)
-public class DokkaJavadocJarMojo : AbstractDokkaMojo(listOf(javadocDependency)) {
-
- /**
- * Directory to which documentation jar will be generated.
- *
- * Default is `{project.basedir}/target/dokkaJavadocJar`.
- */
- @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokkaJavadocJar")
- public var outputDir: String = ""
-
- /**
- * Specifies the directory where the generated jar file will be put.
- */
- @Parameter(property = "project.build.directory")
- private var jarOutputDirectory: String? = null
-
- /**
- * Specifies the filename that will be used for the generated jar file. Please note that `-javadoc`
- * or `-test-javadoc` will be appended to the file name.
- */
- @Parameter(property = "project.build.finalName")
- private var finalName: String? = null
-
- /**
- * Specifies whether to attach the generated artifact to the project helper.
- */
- @Parameter(property = "attach", defaultValue = "true")
- private val attach: Boolean = false
-
- /**
- * The archive configuration to use.
- * See [Maven Archiver Reference](https://maven.apache.org/shared/maven-archiver/index.html)
- */
- @Parameter
- private val archive = MavenArchiveConfiguration()
-
- @Parameter(property = "maven.javadoc.classifier", defaultValue = "javadoc", required = true)
- private var classifier: String? = null
-
- @Component
- private var projectHelper: MavenProjectHelper? = null
-
- @Component(role = Archiver::class, hint = "jar")
- private var jarArchiver: JarArchiver? = null
-
- override fun getOutDir(): String = outputDir
-
- override fun execute() {
- super.execute()
- if (!File(outputDir).exists()) {
- log.warn("No javadoc generated so no javadoc jar will be generated")
- return
- }
- val outputFile = generateArchive("$finalName-$classifier.jar")
- if (attach) {
- projectHelper?.attachArtifact(mavenProject, "javadoc", classifier, outputFile)
- }
- }
-
- private fun generateArchive(jarFileName: String): File {
- val javadocJar = File(jarOutputDirectory, jarFileName)
-
- val archiver = MavenArchiver()
- archiver.archiver = jarArchiver
- archiver.setOutputFile(javadocJar)
- archiver.archiver.addFileSet(DefaultFileSet().apply { directory = File(outputDir) })
-
- archive.isAddMavenDescriptor = false
- archiver.createArchive(session, mavenProject, archive)
-
- return javadocJar
- }
-}
-
-private val javadocDependency = Dependency().apply {
- groupId = "org.jetbrains.dokka"
- artifactId = "javadoc-plugin"
-}
diff --git a/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt b/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt
deleted file mode 100644
index 5eb4f269..00000000
--- a/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt
+++ /dev/null
@@ -1,68 +0,0 @@
-/*
- * 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.plugins.annotations.Parameter
-import org.jetbrains.dokka.ExternalDocumentationLink
-import org.jetbrains.dokka.ExternalDocumentationLinkImpl
-import java.net.URL
-
-/**
- * Configuration block that allows creating links leading to externally hosted
- * documentation of your dependencies.
- *
- * For instance, if you are using types from `kotlinx.serialization`, by default
- * they will be unclickable in your documentation, as if unresolved. However,
- * since API reference for `kotlinx.serialization` is also built by Dokka and is
- * [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/),
- * you can configure external documentation links for it, allowing Dokka to generate
- * documentation links for used types, making them clickable and appear resolved.
- *
- * Example:
- *
- * ```xml
- * <externalDocumentationLinks>
- * <link>
- * <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
- * <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
- * </link>
- * </externalDocumentationLinks>
- * ```
- */
-public class ExternalDocumentationLinkBuilder {
-
- /**
- * Root URL of documentation to link with. **Must** contain a trailing slash.
- *
- * Dokka will do its best to automatically find `package-list` for the given URL, and link
- * declarations together.
- *
- * It automatic resolution fails or if you want to use locally cached files instead,
- * consider providing [packageListUrl].
- *
- * Example:
- *
- * ```xml
- * <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
- * ```
- */
- @Parameter(name = "url", required = true)
- public var url: URL? = null
-
- /**
- * Specifies the exact location of a `package-list` instead of relying on Dokka
- * automatically resolving it. Can also be a locally cached file to avoid network calls.
- *
- * Example:
- *
- * ```xml
- * <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
- * ```
- */
- @Parameter(name = "packageListUrl", required = true)
- public var packageListUrl: URL? = null
-
- public fun build(): ExternalDocumentationLinkImpl = ExternalDocumentationLink(url, packageListUrl)
-}
diff --git a/runners/maven-plugin/src/main/kotlin/MavenDokkaLogger.kt b/runners/maven-plugin/src/main/kotlin/MavenDokkaLogger.kt
deleted file mode 100644
index 1bc39d10..00000000
--- a/runners/maven-plugin/src/main/kotlin/MavenDokkaLogger.kt
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- * 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.plugin.logging.Log
-import org.jetbrains.dokka.utilities.DokkaLogger
-import java.util.concurrent.atomic.AtomicInteger
-
-public class MavenDokkaLogger(
- public val log: Log
-) : DokkaLogger {
- private val warningsCounter = AtomicInteger()
- private val errorsCounter = AtomicInteger()
-
- override var warningsCount: Int
- get() = warningsCounter.get()
- set(value) = warningsCounter.set(value)
-
- override var errorsCount: Int
- get() = errorsCounter.get()
- set(value) = errorsCounter.set(value)
-
- override fun debug(message: String) {
- log.debug(message)
- }
-
- override fun info(message: String) {
- log.info(message)
- }
-
- override fun progress(message: String) {
- log.info(message)
- }
-
- override fun warn(message: String) {
- this.log.warn(message).also { warningsCounter.incrementAndGet() }
- }
-
- override fun error(message: String) {
- log.error(message).also { errorsCounter.incrementAndGet() }
- }
-}
diff --git a/runners/maven-plugin/src/main/kotlin/PackageOptions.kt b/runners/maven-plugin/src/main/kotlin/PackageOptions.kt
deleted file mode 100644
index 875fb047..00000000
--- a/runners/maven-plugin/src/main/kotlin/PackageOptions.kt
+++ /dev/null
@@ -1,89 +0,0 @@
-/*
- * 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.plugins.annotations.Parameter
-import org.jetbrains.dokka.DokkaConfiguration
-import org.jetbrains.dokka.DokkaDefaults
-
-/**
- * Configuration block that allows setting some options for specific packages
- * matched by [matchingRegex].
- *
- * Example:
- *
- * ```xml
- * <configuration>
- * <perPackageOptions>
- * <packageOptions>
- * <matchingRegex>.*api.*</matchingRegex>
- * <suppress>false</suppress>
- * <reportUndocumented>false</reportUndocumented>
- * <skipDeprecated>false</skipDeprecated>
- * <documentedVisibilities>
- * <visibility>PUBLIC</visibility>
- * <visibility>PROTECTED</visibility>
- * </documentedVisibilities>
- * </packageOptions>
- * </perPackageOptions>
- * </configuration>
- * ```
- */
-public class PackageOptions : DokkaConfiguration.PackageOptions {
-
- /**
- * Regular expression that is used to match the package.
- *
- * If multiple packages match the same `matchingRegex`, the longest `matchingRegex` will be used.
- *
- * Default is any string: `.*`.
- */
- @Parameter
- override var matchingRegex: String = ".*"
-
- /**
- * Whether this package should be skipped when generating documentation.
- *
- * Default is `false`.
- */
- @Parameter
- override var suppress: Boolean = DokkaDefaults.suppress
-
- /**
- * List of visibility modifiers that should be documented.
- *
- * This can be used if you want to document protected/internal/private declarations within a
- * specific package, as well as if you want to exclude public declarations and only document internal API.
- *
- * Default is [DokkaConfiguration.Visibility.PUBLIC].
- */
- @Parameter(property = "visibility")
- override var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities
-
- /**
- * Whether to document declarations annotated with [Deprecated].
- *
- * Can be set on project level with [AbstractDokkaMojo.skipDeprecated].
- *
- * Default is `false`.
- */
- @Parameter
- override var skipDeprecated: Boolean = DokkaDefaults.skipDeprecated
-
- /**
- * Whether to emit warnings about visible undocumented declarations, that is declarations from
- * this package and without KDocs, after they have been filtered by [documentedVisibilities].
- *
- * This setting works well with [AbstractDokkaMojo.failOnWarning].
- *
- * Default is `false`.
- */
- @Parameter
- override var reportUndocumented: Boolean = DokkaDefaults.reportUndocumented
-
- @Parameter
- @Deprecated("Use [documentedVisibilities] property for a more flexible control over documented visibilities")
- override var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
-}
diff --git a/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt b/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt
deleted file mode 100644
index ee2354aa..00000000
--- a/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt
+++ /dev/null
@@ -1,69 +0,0 @@
-/*
- * 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.plugins.annotations.Parameter
-
-/**
- * Configuration block that allows adding a `source` link to each signature
- * which leads to [path] with a specific line number (configurable by setting [lineSuffix]),
- * letting documentation readers find source code for each declaration.
- *
- * Example:
- *
- * ```xml
- * <sourceLinks>
- * <link>
- * <path>${project.basedir}/src</path>
- * <url>https://github.com/kotlin/dokka/tree/master/src</url>
- * <lineSuffix>#L</lineSuffix>
- * </link>
- * </sourceLinks>
- * ```
- */
-public class SourceLinkMapItem {
-
- /**
- * Path to the local source directory. The path must be relative to the root of current project.
- *
- * Example:
- *
- * ```xml
- * <path>${project.basedir}/src</path>
- * ```
- */
- @Parameter(name = "path", required = true)
- public var path: String = ""
-
- /**
- * URL of source code hosting service that can be accessed by documentation readers,
- * like GitHub, GitLab, Bitbucket, etc. This URL will be used to generate
- * source code links of declarations.
- *
- * Example:
- *
- * ```xml
- * <url>https://github.com/username/projectname/tree/master/src</url>
- * ```
- */
- @Parameter(name = "url", required = true)
- public var url: String = ""
-
- /**
- * Suffix used to append source code line number to the URL. This will help readers navigate
- * not only to the file, but to the specific line number of the declaration.
- *
- * The number itself will be appended to the specified suffix. For instance,
- * if this property is set to `#L` and the line number is 10, resulting URL suffix
- * will be `#L10`
- *
- * Suffixes used by popular services:
- * - GitHub: `#L`
- * - GitLab: `#L`
- * - Bitbucket: `#lines-`
- */
- @Parameter(name = "lineSuffix")
- public var lineSuffix: String? = null
-}