diff options
Diffstat (limited to 'runners/maven-plugin')
| -rw-r--r-- | runners/maven-plugin/api/maven-plugin.api | 141 | ||||
| -rw-r--r-- | runners/maven-plugin/build.gradle.kts | 138 | ||||
| -rw-r--r-- | runners/maven-plugin/pom.template.xml | 56 | ||||
| -rw-r--r-- | runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 615 | ||||
| -rw-r--r-- | runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt | 68 | ||||
| -rw-r--r-- | runners/maven-plugin/src/main/kotlin/MavenDokkaLogger.kt | 44 | ||||
| -rw-r--r-- | runners/maven-plugin/src/main/kotlin/PackageOptions.kt | 89 | ||||
| -rw-r--r-- | runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt | 69 |
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 -} |