Description is rendered into JavaDocs

Getters for parameters and group now have JavaDoc comments containing
the stripped description.

Resolves #53

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Version 1.3
 * [New] [#18](https://github.com/gradlex-org/build-parameters/issues/18) Fail the build when it's running on an unsupported Gradle version
 * [New] [#52](https://github.com/gradlex-org/build-parameters/issues/52) Groups should have a description
+* [New] [#53](https://github.com/gradlex-org/build-parameters/issues/53) Render descriptions into getters JavaDoc
 
 ## Version 1.2
 * [New] [#42](https://github.com/gradlex-org/build-parameters/issues/42) Boolean parameters: empty string maps to 'true' and invalid value fails the build (instead of silently mapping to 'false')

src/main/java/org/gradlex/buildparameters/CodeGeneratingBuildParameter.java

@@ -16,6 +16,10 @@
 
 package org.gradlex.buildparameters;
 
+import org.gradle.api.provider.Property;
+
+import java.util.Arrays;
+import java.util.Collections;
 import java.util.function.Function;
 
 interface CodeGeneratingBuildParameter {
@@ -26,6 +30,8 @@ interface CodeGeneratingBuildParameter {
 
     Identifier getId();
 
+    Property<String> getDescription();
+
     static CodeGeneratingBuildParameter from(BuildParameter<?> parameter, BuildParameterGroup containingGroup) {
         ParameterType type;
         if (parameter instanceof IntegerBuildParameter) {
@@ -78,6 +84,11 @@ private String getDefaultValue() {
         public Identifier getId() {
             return parameter.id;
         }
+
+        @Override
+        public Property<String> getDescription() {
+            return parameter.getDescription();
+        }
     }
 
     class ParameterWithoutDefault implements CodeGeneratingBuildParameter {
@@ -109,6 +120,11 @@ public String getValue() {
         public Identifier getId() {
             return parameter.id;
         }
+
+        @Override
+        public Property<String> getDescription() {
+            return parameter.getDescription();
+        }
     }
 
     class ParameterType {

src/main/java/org/gradlex/buildparameters/PluginCodeGeneration.java

@@ -30,6 +30,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.stream.Collectors;
 
 import static org.gradlex.buildparameters.Constants.GENERATED_EXTENSION_CLASS_NAME;
 import static org.gradlex.buildparameters.Constants.GENERATED_EXTENSION_NAME;
@@ -105,11 +106,13 @@ private void generateGroupClass(BuildParameterGroup group) {
         }
         lines.add("    }");
         for (BuildParameterGroup subGroup : subGroups) {
+            renderJavaDoc(lines, subGroup.getDescription());
             lines.add("    public " + subGroup.id.toFullQualifiedTypeName() + " get" + subGroup.id.toSimpleTypeName() + "() {");
             lines.add("        return this." + subGroup.id.toFieldName() + ";");
             lines.add("    }");
         }
         for (CodeGeneratingBuildParameter parameter : parameters) {
+            renderJavaDoc(lines, parameter.getDescription());
             lines.add("    public " + parameter.getType() + " get" + capitalize(parameter.getId().toFieldName()) + "() {");
             lines.add("        return this." + parameter.getId().toFieldName() + ";");
             lines.add("    }");
@@ -120,6 +123,20 @@ private void generateGroupClass(BuildParameterGroup group) {
         write(groupSource, lines);
     }
 
+    private void renderJavaDoc(List<String> lines, Property<String> description) {
+        if (description.isPresent()) {
+            List<String> descriptionLines = Arrays.stream(description.get().split(System.lineSeparator()))
+                    .map(String::trim)
+                    .collect(Collectors.toCollection(ArrayList::new));
+
+            StringLists.dropLeadingAndTrailingEmptyLines(descriptionLines);
+
+            lines.add("    /**");
+            descriptionLines.forEach(l -> lines.add("     * " + l.trim()));
+            lines.add("     */");
+        }
+    }
+
     private void generateEnumClass(EnumBuildParameter enumBuildParameter) {
         getOutputDirectory().get().dir(enumBuildParameter.id.toPackageFolderPath()).getAsFile().mkdirs();
         Path enumSource = getOutputDirectory().get().file(enumBuildParameter.id.toPackageFolderPath() + "/" + enumBuildParameter.id.toSimpleTypeName() + ".java").getAsFile().toPath();

src/main/java/org/gradlex/buildparameters/StringLists.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2022 the GradleX team.
+ *
+ * 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
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.gradlex.buildparameters;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.ListIterator;
+
+class StringLists {
+
+    private StringLists() {
+    }
+
+    static void dropLeadingAndTrailingEmptyLines(List<String> input) {
+        dropLeadingEmptyLines(input);
+        dropTrailingEmptyLines(input);
+    }
+
+    static void dropLeadingEmptyLines(List<String> input) {
+        Iterator<String> it = input.iterator();
+        boolean nonEmptyLineReached = false;
+        while (it.hasNext() && !nonEmptyLineReached) {
+            String line = it.next();
+            if (line.isEmpty()) {
+                it.remove();
+            } else {
+                nonEmptyLineReached = true;
+            }
+        }
+    }
+
+    public static void dropTrailingEmptyLines(List<String> input) {
+        ListIterator<String> it = input.listIterator(input.size());
+        boolean nonEmptyLineReached = false;
+        while (it.hasPrevious() && !nonEmptyLineReached) {
+            String line = it.previous();
+            if (line.isEmpty()) {
+                it.remove();
+            } else {
+                nonEmptyLineReached = true;
+            }
+        }
+    }
+}

src/test/groovy/org/gradlex/buildparameters/CodeGenerationFuncTest.groovy

@@ -123,4 +123,78 @@ class CodeGenerationFuncTest extends Specification {
         result.output.contains("Configuration cache entry reused.")
     }
 
+    def "it renders descriptions of parameters and groups as JavaDocs of getters"() {
+        when:
+        build("build")
+
+        then:
+        def parameterJavaDoc =
+        """ |    /**
+            |     * A simple string parameter
+            |     */
+            |    public String getMyParameter()""".stripMargin("|")
+        generatedFile("buildparameters/BuildParametersExtension.java").text.contains(parameterJavaDoc)
+
+        and:
+        def groupJavaDoc =
+        """ |    /**
+            |     * Group description
+            |     */
+            |    public buildparameters.MyGroup getMyGroup()""".stripMargin("|")
+        generatedFile("buildparameters/BuildParametersExtension.java").text.contains(groupJavaDoc)
+    }
+
+    def "it renders multiline descriptions as multi line JavaDoc comments"() {
+        given:
+        buildFile << """
+            buildParameters {
+                integer("myInt") {
+                    description = ${'"""'}
+                        A multi line
+                        description for
+                        
+                        an int parameter.
+                    ${'"""'}
+                    defaultValue = 42
+                }
+                group("someGroup") {
+                    description = ${'"""'}
+                        A multi line
+                        description for
+                        
+                        a group.
+                    ${'"""'}
+                }
+            }
+        """
+
+        when:
+        build("build")
+
+        then:
+        def parameterJavaDoc =
+        """ |    /**
+            |     * A multi line
+            |     * description for
+            |     * 
+            |     * an int parameter.
+            |     */
+            |    public int getMyInt()""".stripMargin("|")
+        generatedFile("buildparameters/BuildParametersExtension.java").text.contains(parameterJavaDoc)
+
+        and:
+        def groupJavaDoc =
+        """ |    /**
+            |     * A multi line
+            |     * description for
+            |     * 
+            |     * a group.
+            |     */
+            |    public buildparameters.SomeGroup getSomeGroup()""".stripMargin("|")
+        generatedFile("buildparameters/BuildParametersExtension.java").text.contains(groupJavaDoc)
+    }
+
+    private File generatedFile(String path) {
+        projectDir.file("build/generated/sources/build-parameters-plugin/java/main/$path")
+    }
 }