Add Dokka configuration to kotlinx-metadata-jvm

libraries/kotlinx-metadata/jvm/api/kotlinx-metadata-jvm.api

@@ -131,6 +131,7 @@ public final class kotlinx/metadata/KmAnnotation {
 }
 
 public abstract class kotlinx/metadata/KmAnnotationArgument {
+	public abstract fun toString ()Ljava/lang/String;
 }
 
 public final class kotlinx/metadata/KmAnnotationArgument$AnnotationValue : kotlinx/metadata/KmAnnotationArgument {

libraries/kotlinx-metadata/jvm/build.gradle.kts

@@ -7,6 +7,7 @@ plugins {
     kotlin("jvm")
     id("jps-compatible")
     id("org.jetbrains.kotlinx.binary-compatibility-validator")
+    id("org.jetbrains.dokka")
 }
 
 /*
@@ -73,6 +74,32 @@ apiValidation {
     )
 }
 
+tasks.dokkaHtml.configure {
+    outputDirectory.set(buildDir.resolve("dokka"))
+    pluginsMapConfiguration.set(
+        mapOf(
+            "org.jetbrains.dokka.base.DokkaBase"
+                    to """{ "templatesDir": "${projectDir.toString().replace('\\', '/')}/dokka-templates" }"""
+        )
+    )
+
+    dokkaSourceSets.configureEach {
+        includes.from(project.file("dokka/moduledoc.md").path)
+
+        sourceRoots.from(project(":kotlinx-metadata").getSources())
+
+        skipDeprecated.set(true)
+        reportUndocumented.set(true)
+        failOnWarning.set(true)
+
+        perPackageOption {
+            matchingRegex.set("kotlinx\\.metadata\\.internal(\$|\\.).*")
+            suppress.set(true)
+            reportUndocumented.set(false)
+        }
+    }
+}
+
 sourcesJar()
 
 javadocJar()

libraries/kotlinx-metadata/jvm/dokka-templates/README.md

@@ -0,0 +1,12 @@
+# Dokka's template customization
+To provide unified navigation for all parts of [kotlinlang.org](https://kotlinlang.org/),
+the Kotlin Website Team uses this directory to place custom templates in this folder
+during the website build time on TeamCity.
+
+It is not practical to place these templates in the kotlinx.metadata repository because they change from time to time
+and aren't related to the library's release cycle.
+
+The folder is defined as a source for custom templates by the templatesDir property through Dokka's plugin configuration.
+
+[Here](https://kotlinlang.org/docs/dokka-html.html#templates), you can
+find more about the customization of Dokka's HTML output.

libraries/kotlinx-metadata/jvm/dokka/moduledoc.md

@@ -0,0 +1,7 @@
+# Package kotlinx.metadata
+
+Contains core data structures representing metadata of various Kotlin declarations.
+
+# Package kotlinx.metadata.jvm
+
+Contains entry points for parsing metadata produced by Kotlin compiler for JVM and JVM-specific structures and extensions.

libraries/kotlinx-metadata/src/kotlinx/metadata/annotations.kt

@@ -46,6 +46,11 @@ class KmAnnotation(val className: ClassName, val arguments: Map<String, KmAnnota
  */
 @Suppress("IncorrectFormatting") // one-line KDoc
 sealed class KmAnnotationArgument {
+
+    // Avoid triggering Dokka configured for failing on undocumented functions
+    /** @suppress */
+    abstract override fun toString(): String
+
     /**
      * A kind of annotation argument, whose value is directly accessible via [value].
      * This is possible for annotation arguments of primitive types, unsigned types, and strings.