Update Dokka with a bit more configuration.

pdvrieze · pdvrieze · commit d375df5bf1ee · 2023-09-18T20:55:27.000+01:00
diff --git a/buildSrc/src/main/kotlin/dokka.kt b/buildSrc/src/main/kotlin/dokka.kt
@@ -21,23 +21,21 @@
 package net.devrieze.gradle.ext
 
 import org.gradle.api.Project
+import org.gradle.api.provider.Provider
+import org.gradle.kotlin.dsl.assign
 import org.gradle.kotlin.dsl.withType
+import org.jetbrains.dokka.Platform
+import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
 import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.dokka.gradle.DokkaTaskPartial
 import org.jetbrains.dokka.gradle.GradleDokkaSourceSetBuilder
+import java.net.URL
 
 fun Project.configureDokka(
     myModuleName: String = name,
     myModuleVersion: String? = property("xmlutil_version") as String?
 ) {
-    tasks.withType<DokkaTask> {
-        moduleName.set(myModuleName)
-        myModuleVersion.let { moduleVersion.set(it) }
-        dokkaSourceSets.configureEach {
-            this@configureDokka.configureDokkaSourceSet(this)
-        }
-    }
-    tasks.withType<DokkaTaskPartial> {
+    tasks.withType<AbstractDokkaLeafTask> {
         moduleName.set(myModuleName)
         myModuleVersion.let { moduleVersion.set(it) }
         dokkaSourceSets.configureEach {
@@ -48,38 +46,62 @@ fun Project.configureDokka(
 
 private fun Project.configureDokkaSourceSet(
     sourceSet: GradleDokkaSourceSetBuilder
-) = with(sourceSet) {
-    logger.lifecycle("Configuring dokka on sourceSet: $name = ${displayName.orNull}")
-    if (name.startsWith("android")) {
-        noAndroidSdkLink.set(false)
-        noJdkLink.set(true)
-    } else {
-        noAndroidSdkLink.set(true)
-        noJdkLink.set(false)
-    }
-    displayName.set(
-        when (val dn = displayName.get()) {
-            "jvm" -> "JVM"
-            "android" -> "Android"
-            "common" -> "Common"
-            "js" -> "JS"
-            else -> dn
-        }
-    )
-    includeNonPublic.set(false)
-    skipEmptyPackages.set(true)
-    skipDeprecated.set(true)
-    perPackageOption {
-        matchingRegex.set(".*\\.(impl|internal)(|\\..*)")
-        suppress.set(true)
-    }
-    if ("Main" in name) {
-        val readme = project.file(project.relativePath("src/README.md"))
-        if (readme.exists() && readme.canRead()) {
-            includes.from(listOf(readme))
-            logger.lifecycle("Adding $readme to sourceSet ${project.name}:${name}(${displayName.orNull})")
-        } else {
-            logger.warn("Missing $readme for project ${project.name}")
+) {
+    if (!sourceSet.suppress.get()) {
+        with(sourceSet) {
+            if (name.startsWith("android")) {
+                noAndroidSdkLink.set(false)
+                noJdkLink.set(true)
+            } else {
+                noAndroidSdkLink.set(true)
+                noJdkLink.set(false)
+            }
+            displayName.set(
+                when (val dn = displayName.get()) {
+                    "jvm" -> "JVM"
+                    "android" -> "Android"
+                    "common" -> "Common"
+                    "js" -> "JS"
+                    "native" -> "Native"
+                    else -> dn
+                }
+            )
+            logger.lifecycle("Configuring dokka on sourceSet: $name = ${displayName.orNull}")
+
+            includeNonPublic = false
+            skipEmptyPackages = true
+            skipDeprecated = true
+
+            for (sourceRoot in sourceSet.sourceRoots) {
+                val relativeRoot = sourceRoot.relativeTo(rootProject.projectDir)
+                logger.lifecycle("Adding source link for root: $relativeRoot")
+                sourceLink {
+                    localDirectory = sourceRoot
+                    remoteUrl = URL("https://github.com/pdvrieze/xmlutil/tree/master/${relativeRoot}")
+                }
+            }
+
+            externalDocumentationLink {
+                url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/"))
+                packageListUrl.set(
+                    rootProject.projectDir.resolve("serialization.package.list").toURL()
+                )
+            }
+
+            perPackageOption {
+                matchingRegex.set(".*\\.(impl|internal)(|\\..*)")
+                suppress.set(true)
+            }
+            logger.lifecycle("Dokka source set: '$name'")
+            if ("Main" in name) {
+                val readme = project.file(project.relativePath("src/README.md"))
+                if (readme.exists() && readme.canRead()) {
+                    includes.from(listOf(readme))
+                    logger.lifecycle("Adding $readme to sourceSet :${project.name}:${name}(${displayName.orNull})")
+                } else {
+                    logger.warn("Missing $readme for project ${project.name}")
+                }
+            }
         }
     }
 }
diff --git a/core/src/README.md b/core/src/README.md
@@ -1,7 +1,8 @@
 # Module core
 Core Xml wrapper that provides xmlpull parsing functionality. This module
 is designed to wrap the actually present xml functionality in the platform.
-As such it is currently limited to JVM, Android and JS(browser) platforms.
+In addition, this module provides a platform independent implementation
+based upon the Android code.
 
 # Package nl.adaptivity.js.util
 Package with various extension functions to make working with DOM nodes
@@ -15,4 +16,4 @@ The access point to the package/module is (XmlStreaming)[nl.adaptivity.xml.XmlSt
 
 # Package nl.adaptivity.xmlutil.util
 Package with various utility types that are generally allow for a more
-convenient way of using the library.
+convenient way of using the library.
diff --git a/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/DomWriter.kt b/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/DomWriter.kt
@@ -27,7 +27,7 @@ import nl.adaptivity.xmlutil.util.impl.*
 import nl.adaptivity.xmlutil.dom.*
 
 /**
- * Created by pdvrieze on 04/04/17.
+ * Writer that uses the DOM for the underlying storage (rather than writing to some string).
  */
 public class DomWriter constructor(
     current: Node?,
diff --git a/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/XmlWriter.kt b/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/XmlWriter.kt
@@ -37,7 +37,7 @@ import kotlin.jvm.JvmOverloads
 public interface XmlWriter : Closeable {
 
     /**
-     * The current depth into the tree.
+     * The current depth into the tree. The initial depth is `0`
      */
     public val depth: Int
 
@@ -73,12 +73,21 @@ public interface XmlWriter : Closeable {
         namespaceAttr(namespacePrefix.toString(), namespaceUri.toString())
     }
 
+    /**
+     * Write a namespace declaration attribute.
+     */
     public fun namespaceAttr(namespacePrefix: String, namespaceUri: String)
 
+    /**
+     * Write a namespace declaration attribute.
+     */
     public fun namespaceAttr(namespace: Namespace) {
         namespaceAttr(namespace.prefix, namespace.namespaceURI)
     }
 
+    /**
+     * Close the writer. After invoking this the writer is not writable.
+     */
     override fun close()
 
     /**
@@ -87,11 +96,9 @@ public interface XmlWriter : Closeable {
     public fun flush()
 
     /**
-     * Write a start tag.
+     * Write a start tag. This increases the current depth.
      * @param namespace The namespace to use for the tag.
-     *
      * @param localName The local name for the tag.
-     *
      * @param prefix The prefix to use, or `null` for the namespace to be assigned automatically
      */
     public fun startTag(namespace: String?, localName: String, prefix: String?)
@@ -114,25 +121,71 @@ public interface XmlWriter : Closeable {
      */
     public fun cdsect(text: String)
 
+    /**
+     * Write an entity reference
+     * @param text the name of the reference. Must be a valid reference name.
+     */
     public fun entityRef(text: String)
 
+    /**
+     * Write a processing instruction with the given raw content. When using, prefer the version taking two arguments
+     */
     public fun processingInstruction(text: String)
 
+    /**
+     * Write a processing instruction with the given target and data
+     * @param target The (CNAME) target of the instruction
+     * @param data The data to be used.
+     */
     public fun processingInstruction(target: String, data: String): Unit =
         processingInstruction("$target $data")
 
+    /**
+     * Write ignorable whitespace.
+     * @param text This text is expected to be only XML whitespace.
+     */
     public fun ignorableWhitespace(text: String)
 
+    /**
+     * Write an attribute.
+     * @param namespace The namespace of the attribute. `null` and `""` will both resolve to the empty namespace.
+     * @param name The local name of the attribute (CName, must exclude the prefix).
+     * @param prefix The prefix to use. Note that in XML for attributes the prefix is empty/null when the namespace is and vice versa.
+     * @param value The value of the attribute
+     */
     public fun attribute(namespace: String?, name: String, prefix: String?, value: String)
 
+    /**
+     * Write a document declaration (DTD).
+     * @param The content of the DTD Declaration.
+     */
     public fun docdecl(text: String)
 
+    /**
+     * Start the document. This causes an xml declaration to be generated with the relevant content.
+     * @param version The XML version
+     * @param encoding The encoding of the document
+     * @param standalone A statement that the document is standalone (no externally defined entities...)
+     */
     public fun startDocument(version: String? = null, encoding: String? = null, standalone: Boolean? = null)
 
+    /**
+     * Close the document. This will do checks, and update the state, but there is no actual content in an xml stream
+     * that corresponds to it.
+     */
     public fun endDocument()
 
+    /**
+     * Write a closing tag.
+     * @param namespace The namespace for the tag to close
+     * @param localName The local name
+     * @param prefix The prefix
+     */
     public fun endTag(namespace: String?, localName: String, prefix: String?)
 
+    /**
+     * A namespace context that provides access to known namespaces/prefixes at this point in the writer.
+     */
     public val namespaceContext: NamespaceContext
 
     /**
@@ -146,7 +199,13 @@ public interface XmlWriter : Closeable {
     public fun getPrefix(namespaceUri: String?): String?
 }
 
-
+/**
+ * Function that collects namespaces not present in the writer
+ * @receiver The writer where namespace information is looked up from
+ * @param reader The reader from which the namespace information is retrieved
+ * @param missingNamespaces Map to which the "missing" namespace is added.
+ */
+@Deprecated("This function should be internal")
 public fun XmlWriter.addUndeclaredNamespaces(reader: XmlReader, missingNamespaces: MutableMap<String, String>) {
     undeclaredPrefixes(reader, missingNamespaces)
 }
diff --git a/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/annotations.kt b/core/src/commonMain/kotlin/nl/adaptivity/xmlutil/annotations.kt
@@ -21,6 +21,10 @@
 package nl.adaptivity.xmlutil
 
 
+/**
+ * Annotation to signify that the annotated code is internal to the XmlUtil module, and no API
+ * stability is guaranteed.
+ */
 @Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY_GETTER)
 @RequiresOptIn("This function is internal to the XmlUtil modules. No api stability is guaranteed", RequiresOptIn.Level.ERROR)
 public annotation class XmlUtilInternal
diff --git a/iconsource_16_9.svg b/iconsource_16_9.svg
diff --git a/pages b/pages
