diff --git a/README.md b/README.md index d8640e0..387f1bb 100644 --- a/README.md +++ b/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. diff --git a/demo-project/groovy/build.gradle b/demo-project/groovy/build.gradle index 5fb2785..bb87d1f 100644 --- a/demo-project/groovy/build.gradle +++ b/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}\"") diff --git a/demo-project/kts/build.gradle.kts b/demo-project/kts/build.gradle.kts index c58d5f3..d2c9c62 100644 --- a/demo-project/kts/build.gradle.kts +++ b/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\"") } diff --git a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigClassSpec.kt b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigClassSpec.kt index 8db8d94..f6c406f 100644 --- a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigClassSpec.kt +++ b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigClassSpec.kt @@ -25,6 +25,10 @@ interface BuildConfigClassSpec : Named { @get:Nested val buildConfigFields: NamedDomainObjectContainer + @get:Input + @get:Optional + val documentation: Property + fun className(className: String) = apply { this.className.set(className) } diff --git a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTask.kt b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTask.kt index eb6fae3..cca3950 100644 --- a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTask.kt +++ b/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) diff --git a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigGeneratorSpec.kt b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigGeneratorSpec.kt index 4f76858..a47d57b 100644 --- a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigGeneratorSpec.kt +++ b/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, val outputDir: File, ) diff --git a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigJavaGenerator.kt b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigJavaGenerator.kt index aab9503..3e1f28e 100644 --- a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigJavaGenerator.kt +++ b/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) diff --git a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigKotlinGenerator.kt b/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigKotlinGenerator.kt index cb9441d..c114683 100644 --- a/plugin/src/main/kotlin/com/github/gmazzo/gradle/plugins/generators/BuildConfigKotlinGenerator.kt +++ b/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): FileSpec.Builder = when { - topLevelConstants -> fields.fold(this, FileSpec.Builder::addProperty) + private fun FileSpec.Builder.addFields(fields: List, 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() diff --git a/plugin/src/test/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTaskTest.kt b/plugin/src/test/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTaskTest.kt index 88edb22..6a43106 100644 --- a/plugin/src/test/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTaskTest.kt +++ b/plugin/src/test/kotlin/com/github/gmazzo/gradle/plugins/BuildConfigTaskTest.kt @@ -17,6 +17,7 @@ class BuildConfigTaskTest { private val spec: BuildConfigClassSpec = project.objects.newInstance("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, )