Added support for documentation in the DSL

README.md

@@ -146,6 +146,17 @@ const val APP_NAME: String = "example-kts"
 
 const val APP_VERSION: String = "0.0.1"
 ```
+
+## Added documentation (JavaDoc / KDoc) to the generated class
+On your `build.gradle.kts` add:
+```kotlin
+buildConfig {
+    documentation.set("Generated by BuildConfig plugin")
+}
+```
+> [!NOTE]
+> `documentation` applies independently for each generated class
+
 ## Values greater than 100 characters
 In some cases, such as embedded public certs, your build config values may exceed 100 characters in length and will become subject to line wrapping by the [Kotlin Poet](https://square.github.io/kotlinpoet/#spaces-wrap-by-default) output. If you need to workaround this behavior, you can explicitly control or prevent line wrapping by replacing spaces with a `·` character.
 

demo-project/groovy/build.gradle

@@ -8,6 +8,7 @@ dependencies {
 }
 
 buildConfig {
+    documentation = "This is a generated BuildConfig class"
     packageName("com.github.gmazzo.buildconfig.demos.groovy")
 
     buildConfigField('String', 'APP_NAME', "\"${project.name}\"")

demo-project/kts/build.gradle.kts

@@ -1,7 +1,7 @@
 import com.github.gmazzo.gradle.plugins.generators.BuildConfigGenerator
 import com.github.gmazzo.gradle.plugins.generators.BuildConfigGeneratorSpec
 import java.io.FileOutputStream
-import java.util.*
+import java.util.Properties
 
 plugins {
     kotlin("jvm")
@@ -23,6 +23,8 @@ tasks.check {
 }
 
 buildConfig {
+    documentation = "This is a generated BuildConfig class"
+
     buildConfigField("String", "APP_NAME", "\"${project.name}\"")
     buildConfigField("String", "APP_VERSION", provider { "\"${project.version}\"" })
     buildConfigField("String", "APP_SECRET", "\"Z3JhZGxlLWphdmEtYnVpbGRjb25maWctcGx1Z2lu\"")
@@ -39,6 +41,7 @@ buildConfig {
 val versionsSS = buildConfig.sourceSets.register ("Versions") {
     useKotlinOutput { topLevelConstants = true }
 
+    documentation = "My list of versions"
     buildConfigField("String", "myDependencyVersion", "\"1.0.1\"")
 }
 

plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigClassSpec.kt

@@ -25,6 +25,10 @@ interface BuildConfigClassSpec : Named {
     @get:Nested
     val buildConfigFields: NamedDomainObjectContainer<BuildConfigField>
 
+    @get:Input
+    @get:Optional
+    val documentation: Property<String>
+
     fun className(className: String) = apply {
         this.className.set(className)
     }

plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTask.kt

@@ -45,6 +45,7 @@ abstract class BuildConfigTask : DefaultTask() {
                 BuildConfigGeneratorSpec(
                     className = className,
                     packageName = packageName,
+                    documentation = it.documentation.orNull,
                     fields = it.buildConfigFields.sortedWith { a, b ->
                         when (val cmp = a.position.get().compareTo(b.position.get())) {
                             0 -> a.name.compareTo(b.name)

plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigGeneratorSpec.kt

@@ -6,6 +6,7 @@ import java.io.File
 data class BuildConfigGeneratorSpec(
     val className: String,
     val packageName: String,
+    val documentation: String?,
     val fields: Collection<BuildConfigField>,
     val outputDir: File,
 )

plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigJavaGenerator.kt

@@ -1,6 +1,11 @@
 package com.github.gmazzo.gradle.plugins.generators
 
-import com.squareup.javapoet.*
+import com.squareup.javapoet.ClassName
+import com.squareup.javapoet.FieldSpec
+import com.squareup.javapoet.JavaFile
+import com.squareup.javapoet.MethodSpec
+import com.squareup.javapoet.TypeName
+import com.squareup.javapoet.TypeSpec
 import org.apache.commons.lang3.ClassUtils
 import org.gradle.api.logging.Logging
 import org.gradle.api.tasks.Input
@@ -22,6 +27,10 @@ data class BuildConfigJavaGenerator(
             typeSpec.addModifiers(Modifier.PUBLIC)
         }
 
+        if (spec.documentation != null) {
+            typeSpec.addJavadoc("\$L", spec.documentation)
+        }
+
         spec.fields.forEach {
             val typeName = when (it.type.get()) {
                 "String" -> TypeName.get(String::class.java)

plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigKotlinGenerator.kt

@@ -1,7 +1,21 @@
 package com.github.gmazzo.gradle.plugins.generators
 
 import com.github.gmazzo.gradle.plugins.BuildConfigField
-import com.squareup.kotlinpoet.*
+import com.squareup.kotlinpoet.BOOLEAN
+import com.squareup.kotlinpoet.BYTE
+import com.squareup.kotlinpoet.CHAR
+import com.squareup.kotlinpoet.ClassName
+import com.squareup.kotlinpoet.DOUBLE
+import com.squareup.kotlinpoet.FLOAT
+import com.squareup.kotlinpoet.FileSpec
+import com.squareup.kotlinpoet.INT
+import com.squareup.kotlinpoet.KModifier
+import com.squareup.kotlinpoet.LONG
+import com.squareup.kotlinpoet.PropertySpec
+import com.squareup.kotlinpoet.SHORT
+import com.squareup.kotlinpoet.TypeSpec
+import com.squareup.kotlinpoet.asClassName
+import com.squareup.kotlinpoet.asTypeName
 import org.apache.commons.lang3.ClassUtils
 import org.gradle.api.logging.Logging
 import org.gradle.api.tasks.Input
@@ -34,15 +48,20 @@ data class BuildConfigKotlinGenerator(
         val fields = spec.fields.asPropertiesSpec()
 
         FileSpec.builder(spec.packageName, spec.className)
-            .addFields(fields)
+            .addFields(fields, spec.documentation)
             .build()
             .writeTo(spec.outputDir)
     }
 
-    private fun FileSpec.Builder.addFields(fields: List<PropertySpec>): FileSpec.Builder = when {
-        topLevelConstants -> fields.fold(this, FileSpec.Builder::addProperty)
+    private fun FileSpec.Builder.addFields(fields: List<PropertySpec>, kdoc: String?): FileSpec.Builder = when {
+        topLevelConstants -> {
+            if (kdoc != null) addFileComment("%L", kdoc)
+            fields.fold(this, FileSpec.Builder::addProperty)
+        }
+
         else -> addType(
             TypeSpec.objectBuilder(name)
+                .apply { if (kdoc != null) addKdoc("%L", kdoc) }
                 .addModifiers(kModifiers)
                 .addProperties(fields)
                 .build()

plugin/src/test/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTaskTest.kt

@@ -17,6 +17,7 @@ class BuildConfigTaskTest {
     private val spec: BuildConfigClassSpec = project.objects.newInstance<DefaultBuildConfigClassSpec>("spec").apply {
         className.set("aClassName")
         packageName.set("aPackage")
+        documentation.set("aJavaDoc")
     }
 
     private val outDir = project.layout.buildDirectory.dir("outDir")
@@ -45,6 +46,7 @@ class BuildConfigTaskTest {
                 BuildConfigGeneratorSpec(
                     className = "aClassName",
                     packageName = "aPackage",
+                    documentation = "aJavaDoc",
                     fields = fields,
                     outputDir = outDir.get().asFile.absoluteFile,
                 )