Fixes Kotlin#3869

- Register binding for `DokkaPluginParametersBuilder` - Remove @internal annotation on `jsonEncode()` for `DokkaPluginParametersBuilder` - Annotate the getter for `DokkaPluginParametersBuilder.objects` (the annotation only works for getters) - Add missing functions for adding files, directories, and maps, which were implied but not present for `DokkaPluginParametersBuilder` - remove overriden `DokkaPluginParametersBuilder.pluginFqn` property as it just caused issues - Add documentation for configuring custom plugins in dokka-migration.md Signed-off-by: solonovamax <[email protected]>
solonovamax · Oct 17, 2024 · 838281b · 838281b
1 parent 7027da8
commit 838281b
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 16 deletions.
diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md
@@ -104,6 +104,11 @@ options according to your project setup:
           customAssets.set(listOf("logo.png"))
           footerMessage.set("(c) Your Company")
       }
+      pluginConfiguration<YourCustomPlugin, YourCustomPluginConfiguration> {
+          stringProperty.set("bar")
+          booleanProperty.set(true)
+          fileListProperty.set(files("foo.txt", "bar.txt"))
+      }
   }
   ```
 
@@ -120,10 +125,19 @@ options according to your project setup:
               remoteLineSuffix.set("#L")
           }
       }
-      pluginsConfiguration.html {
-          customStyleSheets.from("styles.css")
-          customAssets.from("logo.png")
-          footerMessage.set("(c) Your Company")
+      pluginsConfiguration {
+          html {
+              customStyleSheets.from("styles.css")
+              customAssets.from("logo.png")
+              footerMessage.set("(c) Your Company")
+          }
+          pluginParameters("your.package.YourCustomPluginConfiguration") {
+              property("stringProperty", "bar")
+              property("booleanProperty", true)
+              files("fileListProperty") {
+                  from("foo.txt", "bar.txt")
+              }
+          }
       }
   }
   ```
@@ -416,4 +430,4 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
 
 * Explore more [DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). 
 * [Get started with Dokka](dokka-get-started.md).
-* [Learn more about Dokka plugins](dokka-plugins.md).
+* [Learn more about Dokka plugins](dokka-plugins.md).
diff --git a/...unners/dokka-gradle-plugin/src/main/kotlin/engine/plugins/DokkaPluginParametersBuilder.kt b/...unners/dokka-gradle-plugin/src/main/kotlin/engine/plugins/DokkaPluginParametersBuilder.kt
@@ -7,6 +7,7 @@ import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
+import org.gradle.api.Project
 import org.gradle.api.file.ConfigurableFileCollection
 import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.file.RegularFileProperty
@@ -56,17 +57,15 @@ abstract class DokkaPluginParametersBuilder
 @DokkaInternalApi
 constructor(
     name: String,
-    @get:Input
-    override val pluginFqn: String,
-
-    @Internal
+    @get:Internal
     internal val objects: ObjectFactory,
-) : DokkaPluginParametersBaseSpec(name, pluginFqn) {
+    @get:Internal
+    internal val project: Project,
+) : DokkaPluginParametersBaseSpec(name, name) {
 
     @get:Nested
     internal val properties = PluginConfigValue.Properties(objects.mapProperty())
 
-    @Internal
     override fun jsonEncode(): String = properties.convertToJson().toString()
 
     companion object {
@@ -83,17 +82,15 @@ constructor(
                 is PluginConfigValue.Properties ->
                     JsonObject(values.get().mapValues { (_, value) -> value.convertToJson() })
 
-                is PluginConfigValue.Values ->
-                    JsonArray(values.get().map { it.convertToJson() })
+                is PluginConfigValue.Values -> JsonArray(values.get().map { it.convertToJson() })
             }
 
         /** Creates a [JsonPrimitive] from the given [File]. */
-        private fun File?.convertToJson(): JsonPrimitive =
-            JsonPrimitive(this?.canonicalFile?.invariantSeparatorsPath)
+        private fun File?.convertToJson(): JsonPrimitive = JsonPrimitive(this?.canonicalFile?.invariantSeparatorsPath)
     }
 }
 
-
+//region File System Properties
 fun DokkaPluginParametersBuilder.files(
     propertyName: String,
     filesConfig: ConfigurableFileCollection.() -> Unit
@@ -103,6 +100,25 @@ fun DokkaPluginParametersBuilder.files(
     properties.values.put(propertyName, PluginConfigValue.FilesValue(files))
 }
 
+fun DokkaPluginParametersBuilder.file(
+    propertyName: String,
+    file: Any,
+) {
+    val fileProperty = objects.fileProperty()
+    fileProperty.set(project.file(file))
+    properties.values.put(propertyName, PluginConfigValue.FileValue(fileProperty))
+}
+
+fun DokkaPluginParametersBuilder.directory(
+    propertyName: String,
+    directory: Any,
+) {
+    val directoryProperty = objects.directoryProperty()
+    directoryProperty.set(project.file(directory))
+    properties.values.put(propertyName, PluginConfigValue.DirectoryValue(directoryProperty))
+}
+//endregion
+
 //region Primitive Properties
 fun DokkaPluginParametersBuilder.property(propertyName: String, value: String) {
     properties.values.put(propertyName, PluginConfigValue(value))
@@ -169,6 +185,18 @@ fun PluginConfigValue.Values.add(value: Provider<Boolean>) =
 //endregion
 
 
+//region Map Properties
+fun DokkaPluginParametersBuilder.propertiesMap(
+    propertyName: String,
+    build: PluginConfigValue.Properties.() -> Unit
+) {
+    val values = PluginConfigValue.Properties(objects.mapProperty())
+    values.build()
+    properties.values.put(propertyName, values)
+}
+//endregion
+
+
 sealed class PluginConfigValue {
 
     /** An input file */

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaHtmlPlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaHtmlPlugin.kt
@@ -13,6 +13,7 @@ import org.gradle.kotlin.dsl.registerBinding
 import org.gradle.kotlin.dsl.withType
 import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters
 import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters.Companion.DOKKA_HTML_PARAMETERS_NAME
+import org.jetbrains.dokka.gradle.engine.plugins.DokkaPluginParametersBuilder
 import org.jetbrains.dokka.gradle.engine.plugins.DokkaVersioningPluginParameters
 import org.jetbrains.dokka.gradle.engine.plugins.DokkaVersioningPluginParameters.Companion.DOKKA_VERSIONING_PLUGIN_PARAMETERS_NAME
 import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
@@ -35,12 +36,19 @@ constructor(
         HtmlModuleAggregationCheck(archives, providers)
 
     override fun DokkaFormatPluginContext.configure() {
+        registerCustomPluginConfigurationHelper()
         registerDokkaBasePluginConfiguration()
         registerDokkaVersioningPlugin()
         configureHtmlUrlLogging()
         configureModuleAggregation()
     }
 
+    private fun DokkaFormatPluginContext.registerCustomPluginConfigurationHelper() {
+        with(dokkaExtension.pluginsConfiguration) {
+            registerBinding(DokkaPluginParametersBuilder::class, DokkaPluginParametersBuilder::class)
+        }
+    }
+
     private fun DokkaFormatPluginContext.registerDokkaBasePluginConfiguration() {
         with(dokkaExtension.pluginsConfiguration) {
             registerBinding(DokkaHtmlPluginParameters::class, DokkaHtmlPluginParameters::class)