Cleaned up Javadocs

Added support for method parameters as collection
2023-11-27 14:34:07 -08:00 · 2023-11-06 12:56:29 -08:00
11 changed files with 327 additions and 25 deletions
--- a/.idea/intellij-javadocs-4.0.1.xml
+++ b/.idea/intellij-javadocs-4.0.1.xml
@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaDocConfiguration">
+    <GENERAL>
+      <MODE>UPDATE</MODE>
+      <OVERRIDDEN_METHODS>false</OVERRIDDEN_METHODS>
+      <SPLITTED_CLASS_NAME>true</SPLITTED_CLASS_NAME>
+      <LEVELS>
+        <LEVEL>METHOD</LEVEL>
+        <LEVEL>FIELD</LEVEL>
+        <LEVEL>TYPE</LEVEL>
+      </LEVELS>
+      <VISIBILITIES>
+        <VISIBILITY>PUBLIC</VISIBILITY>
+        <VISIBILITY>DEFAULT</VISIBILITY>
+        <VISIBILITY>PROTECTED</VISIBILITY>
+      </VISIBILITIES>
+    </GENERAL>
+    <TEMPLATES>
+      <CLASSES>
+        <CLASS>
+          <KEY>^.*(public|protected|private)*.+interface\s+\w+.*</KEY>
+          <VALUE>/**\n
+ * The interface ${name}.\n
+&lt;#if element.typeParameters?has_content&gt;        * \n
+&lt;/#if&gt;
+&lt;#list element.typeParameters as typeParameter&gt;
+        * @param &lt;${typeParameter.name}&gt; the type parameter\n
+&lt;/#list&gt;
+ */</VALUE>
+        </CLASS>
+        <CLASS>
+          <KEY>^.*(public|protected|private)*.+enum\s+\w+.*</KEY>
+          <VALUE>/**\n
+ * The enum ${name}.\n
+ */</VALUE>
+        </CLASS>
+        <CLASS>
+          <KEY>^.*(public|protected|private)*.+class\s+\w+.*</KEY>
+          <VALUE>/**\n
+ * The type ${name}.\n
+&lt;#if element.typeParameters?has_content&gt;        * \n
+&lt;/#if&gt;
+&lt;#list element.typeParameters as typeParameter&gt;
+        * @param &lt;${typeParameter.name}&gt; the type parameter\n
+&lt;/#list&gt;
+ */</VALUE>
+        </CLASS>
+        <CLASS>
+          <KEY>.+</KEY>
+          <VALUE>/**\n
+ * The type ${name}.\n
+ */</VALUE>
+        </CLASS>
+      </CLASSES>
+      <CONSTRUCTORS>
+        <CONSTRUCTOR>
+          <KEY>.+</KEY>
+          <VALUE>/**\n
+ * Instantiates a new ${name}.\n
+&lt;#if element.parameterList.parameters?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.parameterList.parameters as parameter&gt;
+         * @param ${parameter.name} the ${paramNames[parameter.name]}\n
+&lt;/#list&gt;
+&lt;#if element.throwsList.referenceElements?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.throwsList.referenceElements as exception&gt;
+         * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n
+&lt;/#list&gt;
+ */</VALUE>
+        </CONSTRUCTOR>
+      </CONSTRUCTORS>
+      <METHODS>
+        <METHOD>
+          <KEY>^.*(public|protected|private)*\s*.*(\w(\s*&lt;.+&gt;)*)+\s+get\w+\s*\(.*\).+</KEY>
+          <VALUE>/**\n
+ * Gets ${partName}.\n
+&lt;#if element.typeParameters?has_content&gt;         * \n
+&lt;/#if&gt;
+&lt;#list element.typeParameters as typeParameter&gt;
+         * @param &lt;${typeParameter.name}&gt; the type parameter\n
+&lt;/#list&gt;
+&lt;#if element.parameterList.parameters?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.parameterList.parameters as parameter&gt;
+         * @param ${parameter.name} the ${paramNames[parameter.name]}\n
+&lt;/#list&gt;
+&lt;#if isNotVoid&gt;
+         *\n
+         * @return the ${partName}\n
+&lt;/#if&gt;
+&lt;#if element.throwsList.referenceElements?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.throwsList.referenceElements as exception&gt;
+         * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n
+&lt;/#list&gt;
+ */</VALUE>
+        </METHOD>
+        <METHOD>
+          <KEY>^.*(public|protected|private)*\s*.*(void|\w(\s*&lt;.+&gt;)*)+\s+set\w+\s*\(.*\).+</KEY>
+          <VALUE>/**\n
+ * Sets ${partName}.\n
+&lt;#if element.typeParameters?has_content&gt;         * \n
+&lt;/#if&gt;
+&lt;#list element.typeParameters as typeParameter&gt;
+         * @param &lt;${typeParameter.name}&gt; the type parameter\n
+&lt;/#list&gt;
+&lt;#if element.parameterList.parameters?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.parameterList.parameters as parameter&gt;
+         * @param ${parameter.name} the ${paramNames[parameter.name]}\n
+&lt;/#list&gt;
+&lt;#if isNotVoid&gt;
+         *\n
+         * @return the ${partName}\n
+&lt;/#if&gt;
+&lt;#if element.throwsList.referenceElements?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.throwsList.referenceElements as exception&gt;
+         * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n
+&lt;/#list&gt;
+ */</VALUE>
+        </METHOD>
+        <METHOD>
+          <KEY>^.*((public\s+static)|(static\s+public))\s+void\s+main\s*\(\s*String\s*(\[\s*\]|\.\.\.)\s+\w+\s*\).+</KEY>
+          <VALUE>/**\n
+ * The entry point of application.\n
+
+     &lt;#if element.parameterList.parameters?has_content&gt;
+         *\n
+&lt;/#if&gt;
+     * @param ${element.parameterList.parameters[0].name} the input arguments\n
+&lt;#if element.throwsList.referenceElements?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.throwsList.referenceElements as exception&gt;
+         * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n
+&lt;/#list&gt;
+ */</VALUE>
+        </METHOD>
+        <METHOD>
+          <KEY>.+</KEY>
+          <VALUE>/**\n
+ * ${name}&lt;#if isNotVoid&gt; ${return}&lt;/#if&gt;.\n
+&lt;#if element.typeParameters?has_content&gt;         * \n
+&lt;/#if&gt;
+&lt;#list element.typeParameters as typeParameter&gt;
+         * @param &lt;${typeParameter.name}&gt; the type parameter\n
+&lt;/#list&gt;
+&lt;#if element.parameterList.parameters?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.parameterList.parameters as parameter&gt;
+         * @param ${parameter.name} the ${paramNames[parameter.name]}\n
+&lt;/#list&gt;
+&lt;#if isNotVoid&gt;
+         *\n
+         * @return the ${return}\n
+&lt;/#if&gt;
+&lt;#if element.throwsList.referenceElements?has_content&gt;
+         *\n
+&lt;/#if&gt;
+&lt;#list element.throwsList.referenceElements as exception&gt;
+         * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n
+&lt;/#list&gt;
+ */</VALUE>
+        </METHOD>
+      </METHODS>
+      <FIELDS>
+        <FIELD>
+          <KEY>^.*(public|protected|private)*.+static.*(\w\s\w)+.+</KEY>
+          <VALUE>/**\n
+ * The constant ${element.getName()}.\n
+ */</VALUE>
+        </FIELD>
+        <FIELD>
+          <KEY>^.*(public|protected|private)*.*(\w\s\w)+.+</KEY>
+          <VALUE>/**\n
+    &lt;#if element.parent.isInterface()&gt;
+        * The constant ${element.getName()}.\n
+&lt;#else&gt;
+        * The ${name}.\n
+&lt;/#if&gt; */</VALUE>
+        </FIELD>
+        <FIELD>
+          <KEY>.+</KEY>
+          <VALUE>/**\n
+    &lt;#if element.parent.isEnum()&gt;
+        *${name} ${typeName}.\n
+&lt;#else&gt;
+        * The ${name}.\n
+&lt;/#if&gt;*/</VALUE>
+        </FIELD>
+      </FIELDS>
+    </TEMPLATES>
+  </component>
+</project>
--- a/.idea/libraries/bld.xml
+++ b/.idea/libraries/bld.xml
@ -6,6 +6,7 @@
    </CLASSES>
    <JAVADOC />
    <SOURCES>
+      <root url="file://$PROJECT_DIR$/lib/bld" />
      <root url="jar://$USER_HOME$/.bld/dist/bld-1.7.5-sources.jar!/" />
    </SOURCES>
    <excluded>
@ -14,4 +15,4 @@
    <jarDirectory url="file://$PROJECT_DIR$/lib/bld" recursive="false" />
    <jarDirectory url="file://$PROJECT_DIR$/lib/bld" recursive="false" type="SOURCES" />
  </library>
-</component>
+</component>
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@ -1,3 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="EntryPointsManager">
    <entry_points version="2.0">
@ -28,11 +29,18 @@
    <pattern value="rife.bld.extension.JacocoReportOperation" method="writeReports" />
    <pattern value="rife.bld.extension.JacocoReportOperationBuild" method="pmd" />
    <pattern value="rife.bld.extension.JacocoReportOperation" method="destFile" />
+    <pattern value="rife.bld.extension.JacocoReportOperation" method="isNotBlank" />
  </component>
  <component name="PDMPlugin">
    <option name="customRuleSets">
      <list>
        <option value="$PROJECT_DIR$/config/pmd.xml" />
+        <option value="K:\java\semver\config\pmd.xml" />
+        <option value="$PROJECT_DIR$/../bld-checkstyle/config/pmd.xml" />
+        <option value="$PROJECT_DIR$/../bld-exec/config/pmd.xml" />
+        <option value="$PROJECT_DIR$/../bld-testng/config/pmd.xml" />
+        <option value="$PROJECT_DIR$/../bld-pitest/config/pmd.xml" />
+        <option value="$PROJECT_DIR$/../bld-generated-version/config/pmd.xml" />
      </list>
    </option>
    <option name="skipTestSources" value="false" />
--- a/README.md
+++ b/README.md
@ -21,7 +21,7 @@ public void jacoco() throws IOException {
 }
 ```

-```text
+```console
 ./bld compile jacoco
 ```

--- a/examples/.idea/libraries/bld.xml
+++ b/examples/.idea/libraries/bld.xml
@ -6,6 +6,7 @@
    </CLASSES>
    <JAVADOC />
    <SOURCES>
+      <root url="file://$PROJECT_DIR$/lib/bld" />
      <root url="jar://$USER_HOME$/.bld/dist/bld-1.7.5-sources.jar!/" />
    </SOURCES>
    <excluded>
@ -14,4 +15,4 @@
    <jarDirectory url="file://$PROJECT_DIR$/lib/bld" recursive="false" />
    <jarDirectory url="file://$PROJECT_DIR$/lib/bld" recursive="false" type="SOURCES" />
  </library>
-</component>
+</component>
--- a/examples/README.md
+++ b/examples/README.md
@ -0,0 +1,6 @@
+# Compile and Generate JaCoCo Reports
+
+```console
+./bld compile jacoco
+```
+
--- a/examples/lib/bld/bld-wrapper.properties
+++ b/examples/lib/bld/bld-wrapper.properties
@ -1,6 +1,6 @@
 bld.downloadExtensionJavadoc=false
 bld.downloadExtensionSources=true
-bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.1
+bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.2-SNAPSHOT
 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=
 bld.version=1.7.5
--- a/examples/src/bld/java/com/example/ExamplesBuild.java
+++ b/examples/src/bld/java/com/example/ExamplesBuild.java
@ -20,17 +20,18 @@ public class ExamplesBuild extends Project {
        repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL);

        scope(test)
-                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 0)))
-                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 0)));
+                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 1)))
+                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 1)));
    }

    public static void main(String[] args) {
        new ExamplesBuild().start(args);
    }
+
    @BuildCommand(summary = "Generates Jacoco Reports")
    public void jacoco() throws IOException {
        new JacocoReportOperation()
                .fromProject(this)
                .execute();
    }
-}
+}
--- a/lib/bld/bld-wrapper.properties
+++ b/lib/bld/bld-wrapper.properties
@ -1,6 +1,6 @@
 bld.downloadExtensionJavadoc=false
 bld.downloadExtensionSources=true
-bld.extension-pmd=com.uwyn.rife2:bld-pmd:0.9.3
+bld.extension-pmd=com.uwyn.rife2:bld-pmd:0.9.4
 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=
 bld.version=1.7.5
--- a/src/bld/java/rife/bld/extension/JacocoReportOperationBuild.java
+++ b/src/bld/java/rife/bld/extension/JacocoReportOperationBuild.java
@ -25,7 +25,8 @@ import rife.bld.publish.PublishScm;

 import java.util.List;

-import static rife.bld.dependencies.Repository.*;
+import static rife.bld.dependencies.Repository.MAVEN_CENTRAL;
+import static rife.bld.dependencies.Repository.RIFE2_RELEASES;
 import static rife.bld.dependencies.Scope.*;
 import static rife.bld.operations.JavadocOptions.DocLinkOption.NO_MISSING;

@ -33,7 +34,7 @@ public class JacocoReportOperationBuild extends Project {
    public JacocoReportOperationBuild() {
        pkg = "rife.bld.extension";
        name = "JacocoReportOperation";
-        version = version(0, 9, 1);
+        version = version(0, 9, 2, "SNAPSHOT");

        javaRelease = 17;
        downloadSources = true;
@ -47,12 +48,13 @@ public class JacocoReportOperationBuild extends Project {
        scope(runtime)
                .include(dependency("org.jacoco", "jacoco", jacocoVersion).exclude("*", "org.jacoco.doc"));
        scope(test)
-                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 0)))
-                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 0)))
+                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 1)))
+                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 1)))
                .include(dependency("org.assertj", "assertj-core", version(3, 24, 2)));

        javadocOperation()
                .javadocOptions()
+                .author()
                .docLint(NO_MISSING)
                .link("https://rife2.github.io/bld/")
                .link("https://rife2.github.io/rife2/");
@ -64,13 +66,23 @@ public class JacocoReportOperationBuild extends Project {
                .artifactId("bld-jacoco-report")
                .description("bld Extension to Generate JaCoCo Code Coverage Reports")
                .url("https://github.com/rife2/bld-pmd")
-                .developer(new PublishDeveloper().id("ethauvin").name("Erik C. Thauvin").email("erik@thauvin.net")
-                        .url("https://erik.thauvin.net/"))
-                .license(new PublishLicense().name("The Apache License, Version 2.0")
-                        .url("http://www.apache.org/licenses/LICENSE-2.0.txt"))
-                .scm(new PublishScm().connection("scm:git:https://github.com/rife2/bld-pmd.git")
-                        .developerConnection("scm:git:git@github.com:rife2/bld-pmd.git")
-                        .url("https://github.com/rife2/bld-pmd"))
+                .developer(
+                        new PublishDeveloper()
+                                .id("ethauvin")
+                                .name("Erik C. Thauvin")
+                                .email("erik@thauvin.net")
+                                .url("https://erik.thauvin.net/")
+                )
+                .license(
+                        new PublishLicense()
+                                .name("The Apache License, Version 2.0")
+                                .url("http://www.apache.org/licenses/LICENSE-2.0.txt")
+                )
+                .scm(
+                        new PublishScm().connection("scm:git:https://github.com/rife2/bld-pmd.git")
+                                .developerConnection("scm:git:git@github.com:rife2/bld-pmd.git")
+                                .url("https://github.com/rife2/bld-pmd")
+                )
                .signKey(property("sign.key"))
                .signPassphrase(property("sign.passphrase"));
    }
--- a/src/main/java/rife/bld/extension/JacocoReportOperation.java
+++ b/src/main/java/rife/bld/extension/JacocoReportOperation.java
@ -35,7 +35,7 @@ import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
-import java.util.Arrays;
+import java.util.Collection;
 import java.util.List;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@ -111,14 +111,31 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the locations of Java class files.
-     **/
+     *
+     * @param classFiles the class files
+     * @return this operation instance
+     */
    public JacocoReportOperation classFiles(File... classFiles) {
-        this.classFiles.addAll(Arrays.stream(classFiles).toList());
+        this.classFiles.addAll(List.of(classFiles));
+        return this;
+    }
+
+    /**
+     * Sets the locations of Java class files.
+     *
+     * @param classFiles the class files
+     * @return this operation instance
+     */
+    public JacocoReportOperation classFiles(Collection<File> classFiles) {
+        this.classFiles.addAll(classFiles);
        return this;
    }

    /**
     * Sets the location of the CSV report.
+     *
+     * @param cvs the report location
+     * @return this operation instance
     */
    public JacocoReportOperation csv(File cvs) {
        this.csv = cvs;
@ -127,6 +144,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the file to write execution data to.
+     *
+     * @param destFile the file
+     * @return this operation instance
     */
    public JacocoReportOperation destFile(File destFile) {
        this.destFile = destFile;
@ -135,6 +155,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the source file encoding. The platform encoding is used by default.
+     *
+     * @param encoding the encoding
+     * @return this operation instance
     */
    public JacocoReportOperation encoding(String encoding) {
        this.encoding = encoding;
@ -143,9 +166,23 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the locations of the JaCoCo *.exec files to read.
+     *
+     * @param execFiles the exec files
+     * @return this operation instance
     */
    public JacocoReportOperation execFiles(File... execFiles) {
-        this.execFiles.addAll(Arrays.stream(execFiles).toList());
+        this.execFiles.addAll(List.of(execFiles));
+        return this;
+    }
+
+    /**
+     * Sets the locations of the JaCoCo *.exec files to read.
+     *
+     * @param execFiles the exec files
+     * @return this operation instance
+     */
+    public JacocoReportOperation execFiles(Collection<File> execFiles) {
+        this.execFiles.addAll(execFiles);
        return this;
    }

@ -222,6 +259,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Configure the operation from a {@link BaseProject}.
+     *
+     * @param project the project
+     * @return this operation instance
     */
    public JacocoReportOperation fromProject(BaseProject project) {
        this.project = project;
@ -230,6 +270,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the location of the HTML report.
+     *
+     * @param html the html
+     * @return this operation instance
     */
    public JacocoReportOperation html(File html) {
        this.html = html;
@ -254,6 +297,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the name used for the report.
+     *
+     * @param name the name
+     * @return this operation instance
     */
    public JacocoReportOperation name(String name) {
        this.name = name;
@ -262,6 +308,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Suppresses all output.
+     *
+     * @param quiet {@code true} or {@code false}
+     * @return this operation instance
     */
    public JacocoReportOperation quiet(boolean quiet) {
        this.quiet = quiet;
@ -291,9 +340,23 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the locations of the source files. (e.g., {@code src/main/java})
-     **/
+     *
+     * @param sourceFiles the source files
+     * @return this operation instance
+     */
    public JacocoReportOperation sourceFiles(File... sourceFiles) {
-        this.sourceFiles.addAll(Arrays.stream(sourceFiles).toList());
+        this.sourceFiles.addAll(List.of(sourceFiles));
+        return this;
+    }
+
+    /**
+     * Sets the locations of the source files. (e.g., {@code src/main/java})
+     *
+     * @param sourceFiles the source files
+     * @return this operation instance
+     */
+    public JacocoReportOperation sourceFiles(Collection<File> sourceFiles) {
+        this.sourceFiles.addAll(sourceFiles);
        return this;
    }

@ -308,6 +371,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the tab stop width for the source pages. Default is {@code 4}.
+     *
+     * @param tabWidth the tab width
+     * @return this operation instance
     */
    public JacocoReportOperation tabWidth(int tabWidth) {
        this.tabWidth = tabWidth;
@ -334,6 +400,9 @@ public class JacocoReportOperation extends AbstractOperation<JacocoReportOperati

    /**
     * Sets the location of the XML report.
+     *
+     * @param xml the report location
+     * @return this operation instance
     */
    public JacocoReportOperation xml(File xml) {
        this.xml = xml;
Author	SHA1	Message	Date
Erik C. Thauvin	87bfac676d	Cleaned up Javadocs	2023-11-27 14:34:07 -08:00
Erik C. Thauvin	bbc0a92d23	Added support for method parameters as collection	2023-11-06 12:56:29 -08:00