Merge pull request #55 from gradlex-org/bene/issue/52+53

Handling of descriptions

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 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/BuildParameterGroup.java

@@ -19,8 +19,10 @@
 import org.gradle.api.Action;
 import org.gradle.api.model.ObjectFactory;
 import org.gradle.api.provider.ListProperty;
+import org.gradle.api.provider.Property;
 import org.gradle.api.tasks.Input;
 import org.gradle.api.tasks.Nested;
+import org.gradle.api.tasks.Optional;
 
 import javax.inject.Inject;
 
@@ -35,6 +37,13 @@ public BuildParameterGroup(Identifier identifier) {
         this.id = identifier;
     }
 
+    /**
+     * @since 1.3
+     */
+    @Input
+    @Optional
+    public abstract Property<String> getDescription();
+
     /**
      * @since 1.2
      */

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;
+            }
+        }
+    }
+}