Improve docs of GeneratedMixin

buildSrc/build.gradle.kts

@@ -5,7 +5,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -51,8 +51,8 @@ repositories {
 /**
  * The version of Jackson used by `buildSrc`.
  *
- * Please keep this value in sync. with `io.spine.internal.dependency.Jackson.version`.
- * It's not a requirement, but would be good in terms of consistency.
+ * Please keep this value in sync with [io.spine.internal.dependency.Jackson.version].
+ * It is not a requirement but would be good in terms of consistency.
  */
 val jacksonVersion = "2.15.3"
 
@@ -114,7 +114,7 @@ val protobufPluginVersion = "0.9.4"
  * @see <a href="https://github.com/Kotlin/dokka/releases">
  *     Dokka Releases</a>
  */
-val dokkaVersion = "1.9.10"
+val dokkaVersion = "1.9.20"
 
 /**
  * The version of Detekt Gradle Plugin.

buildSrc/src/main/kotlin/BuildExtensions.kt

@@ -185,3 +185,12 @@ fun Project.configureTaskDependencies() {
         "publishPluginJar".dependOn(createVersionFile)
     }
 }
+
+/**
+ * Obtains all modules of the root project to which this project belongs that
+ * do not have `"-tests"` in their names.
+ *
+ * By convention such modules are for integration tests and should be treated differently.
+ */
+val Project.productionModules: Iterable<Project>
+    get() = rootProject.subprojects.filter { !it.name.contains("-tests") }

buildSrc/src/main/kotlin/DokkaExts.kt

@@ -40,6 +40,8 @@ import org.gradle.kotlin.dsl.DependencyHandlerScope
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
+import org.jetbrains.dokka.gradle.AbstractDokkaTask
 import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.dokka.gradle.GradleDokkaSourceSetBuilder
 
@@ -56,7 +58,7 @@ fun DependencyHandlerScope.useDokkaForKotlinAsJava() {
 
 /**
  * To exclude pieces of code annotated with `@Internal` from the documentation
- * a custom plugin is added to the Dokka's classpath.
+ * a custom plugin is added to the Dokka classpath.
  *
  * @see <a href="https://github.com/SpineEventEngine/dokka-tools/tree/master/dokka-extensions">
  *     Custom Dokka Plugins</a>
@@ -71,12 +73,35 @@ private fun DependencyHandler.dokkaPlugin(dependencyNotation: Any): Dependency?
 private fun Project.dokkaOutput(language: String): File =
     buildDir.resolve("docs/dokka${language.capitalized()}")
 
-private fun Project.dokkaConfigFile(file: String): File {
+fun Project.dokkaConfigFile(file: String): File {
     val dokkaConfDir = project.rootDir.resolve("buildSrc/src/main/resources/dokka")
     return dokkaConfDir.resolve(file)
 }
 
-private fun DokkaTask.configureFor(language: String) {
+/**
+ * Configures the presentation style, logo, and footer message.
+ *
+ * Dokka Base plugin allows setting a few properties to customize the output:
+ * - `customStyleSheets` property to which CSS files are passed overriding
+ *  styles generated by Dokka;
+ * - `customAssets` property to provide resources. The image with the name
+ *  "logo-icon.svg" is passed to override the default logo used by Dokka;
+ * - `separateInheritedMembers` when set to `true`, creates a separate tab in
+ *  type-documentation for inherited members.
+ *
+ * @see <a href="https://kotlin.github.io/dokka/1.8.10/user_guide/base-specific/frontend/#prerequisites">
+ *  Dokka modifying frontend assets</a>
+ */
+fun AbstractDokkaTask.configureStyle() {
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customStyleSheets = listOf(project.dokkaConfigFile("styles/custom-styles.css"))
+        customAssets = listOf(project.dokkaConfigFile("assets/logo-icon.svg"))
+        separateInheritedMembers = true
+        footerMessage = "Copyright ${LocalDate.now().year}, TeamDev"
+    }
+}
+
+private fun AbstractDokkaLeafTask.configureFor(language: String) {
     dokkaSourceSets.configureEach {
         /**
          * Configures links to the external Java documentation.
@@ -85,6 +110,8 @@ private fun DokkaTask.configureFor(language: String) {
 
         skipEmptyPackages.set(true)
 
+        includeNonPublic.set(true)
+
         documentedVisibilities.set(
             setOf(
                 DokkaConfiguration.Visibility.PUBLIC,
@@ -95,38 +122,20 @@ private fun DokkaTask.configureFor(language: String) {
 
     outputDirectory.set(project.dokkaOutput(language))
 
-    /**
-     * Dokka Base plugin allows to set a few properties to customize the output:
-     *
-     * - `customStyleSheets` property to which CSS files are passed overriding
-     * styles generated by Dokka;
-     * - `customAssets` property to provide resources. The image with the name
-     * "logo-icon.svg" is passed to override the default logo used by Dokka;
-     * - `separateInheritedMembers` when set to `true`, creates a separate tab in
-     * type-documentation for inherited members.
-     *
-     * @see <a href="https://kotlin.github.io/dokka/1.8.10/user_guide/base-specific/frontend/#prerequisites">
-     *  Dokka modifying frontend assets</a>
-     */
-    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
-        customStyleSheets = listOf(project.dokkaConfigFile("styles/custom-styles.css"))
-        customAssets = listOf(project.dokkaConfigFile("assets/logo-icon.svg"))
-        separateInheritedMembers = true
-        footerMessage = "Copyright ${LocalDate.now().year}, TeamDev"
-    }
+    configureStyle()
 }
 
 /**
  * Configures this [DokkaTask] to accept only Kotlin files.
  */
-fun DokkaTask.configureForKotlin() {
+fun AbstractDokkaLeafTask.configureForKotlin() {
     configureFor("kotlin")
 }
 
 /**
  * Configures this [DokkaTask] to accept only Java files.
  */
-fun DokkaTask.configureForJava() {
+fun AbstractDokkaLeafTask.configureForJava() {
     configureFor("java")
 }
 

buildSrc/src/main/kotlin/io/spine/internal/dependency/Caffeine.kt

@@ -5,7 +5,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following

buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt

@@ -1,11 +1,11 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -35,7 +35,7 @@ object Dokka {
      * When changing the version, also change the version used in the
      * `buildSrc/build.gradle.kts`.
      */
-    const val version = "1.9.10"
+    const val version = "1.9.20"
 
     object GradlePlugin {
         const val id = "org.jetbrains.dokka"

buildSrc/src/main/kotlin/io/spine/internal/dependency/ProtoData.kt

@@ -65,7 +65,7 @@ object ProtoData {
      * The version of ProtoData dependencies.
      */
     val version: String
-    private const val fallbackVersion = "0.51.0"
+    private const val fallbackVersion = "0.54.2"
 
     /**
      * The distinct version of ProtoData used by other build tools.
@@ -74,7 +74,7 @@ object ProtoData {
      * transitional dependencies, this is the version used to build the project itself.
      */
     val dogfoodingVersion: String
-    private const val fallbackDfVersion = "0.51.0"
+    private const val fallbackDfVersion = "0.54.2"
 
     /**
      * The artifact for the ProtoData Gradle plugin.

buildSrc/src/main/kotlin/io/spine/internal/dependency/Spine.kt

@@ -45,14 +45,14 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/base">spine-base</a>
          */
-        const val base = "2.0.0-SNAPSHOT.203"
+        const val base = "2.0.0-SNAPSHOT.205"
 
         /**
          * The version of [Spine.reflect].
          *
          * @see <a href="https://github.com/SpineEventEngine/reflect">spine-reflect</a>
          */
-        const val reflect = "2.0.0-SNAPSHOT.184"
+        const val reflect = "2.0.0-SNAPSHOT.188"
 
         /**
          * The version of [Spine.Logging].
@@ -89,7 +89,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/mc-java">spine-mc-java</a>
          */
-        const val mcJava = "2.0.0-SNAPSHOT.206"
+        const val mcJava = "2.0.0-SNAPSHOT.217"
 
         /**
          * The version of [Spine.baseTypes].
@@ -124,7 +124,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/tool-base">spine-tool-base</a>
          */
-        const val toolBase = "2.0.0-SNAPSHOT.215"
+        const val toolBase = "2.0.0-SNAPSHOT.223"
 
         /**
          * The version of [Spine.javadocTools].

buildSrc/src/main/kotlin/io/spine/internal/dependency/Validation.kt

@@ -5,7 +5,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -36,17 +36,7 @@ object Validation {
     /**
      * The version of the Validation library artifacts.
      */
-    const val version = "2.0.0-SNAPSHOT.133"
-
-    /**
-     * The distinct version of the Validation library used by build tools during
-     * the transition from a previous version when breaking API changes are introduced.
-     *
-     * When Validation is used both for building the project and as a part of the project's
-     * transitional dependencies, this is the version used to build the project itself to
-     * avoid errors caused by incompatible API changes.
-     */
-    const val dogfoodingVersion = "2.0.0-SNAPSHOT.133"
+    const val version = "2.0.0-SNAPSHOT.154"
 
     const val group = "io.spine.validation"
     private const val prefix = "spine-validation"