Cleaned up Javadocs

.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>

README.md

@@ -24,6 +24,7 @@ public void updateMajor() throws Exception {
             .execute();
 }
 ```
+
 Invoking the `updateMajor` command, will create the `version.propertees`file:
 
 ```sh

examples/.idea/misc.xml

@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="EntryPointsManager">
     <list size="1">

examples/.vscode/launch.json

@@ -1,6 +1,13 @@
 {
     "version": "0.2.0",
     "configurations": [
+        {
+            "type": "java",
+            "name": "PropertyFileExampleBuild",
+            "request": "launch",
+            "mainClass": "com.example.PropertyFileExampleBuild",
+            "projectName": "examples_dbdc9d4b"
+        },
         {
             "type": "java",
             "name": "Run Main",
@@ -18,7 +25,8 @@
                 "--disable-banner",
                 "--disable-ansi-colors",
                 "--exclude-engine=junit-platform-suite",
-                "--exclude-engine=junit-vintage"]
+                "--exclude-engine=junit-vintage"
+            ]
         }
     ]
 }

examples/README.md

@@ -0,0 +1,5 @@
+# Compile and Run Example
+
+```console
+./bld compile run
+```

examples/lib/bld/bld-wrapper.properties

@@ -1,5 +1,5 @@
 #Sun Apr 02 10:32:44 PDT 2023
-bld.extension=com.uwyn.rife2:bld-property-file:0.9.3
+bld.extension=com.uwyn.rife2:bld-property-file:0.9.4-SNAPSHOT
 bld.repositories=MAVEN_LOCAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadExtensionSources=true
 bld.downloadLocation=

examples/src/bld/java/com/example/PropertyFileExampleBuild.java

@@ -40,8 +40,8 @@ public class PropertyFileExampleBuild extends Project {
         repositories = List.of(MAVEN_CENTRAL, RIFE2_RELEASES);
 
         scope(test)
-                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 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, 0)));
+                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 1)));
     }
 
     public static void main(String[] args) {

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.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.1
 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=

src/bld/java/rife/bld/extension/propertyfile/PropertyFileBuild.java

@@ -37,7 +37,7 @@ public class PropertyFileBuild extends Project {
     public PropertyFileBuild() {
         pkg = "rife.bld.extension";
         name = "bld-property-file";
-        version = version(0, 9, 3);
+        version = version(0, 9, 4, "SNAPSHOT");
 
         javaRelease = 17;
         downloadSources = true;
@@ -48,12 +48,13 @@ public class PropertyFileBuild extends Project {
                 .include(dependency("com.uwyn.rife2", "bld", version(1, 7, 5)));
         scope(test)
                 .include(dependency("org.jsoup", "jsoup", version(1, 16, 2)))
-                .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 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, 0)))
+                .include(dependency("org.junit.platform", "junit-platform-console-standalone", version(1, 10, 1)))
                 .include(dependency("org.assertj:assertj-joda-time:2.2.0"));
 
         javadocOperation()
                 .javadocOptions()
+                .author()
                 .docLint(NO_MISSING)
                 .link("https://rife2.github.io/bld/")
                 .link("https://rife2.github.io/rife2/");
@@ -65,15 +66,28 @@ public class PropertyFileBuild extends Project {
                 .artifactId("bld-property-file")
                 .description("bld Extension to Create or Modify Properties Files")
                 .url("https://github.com/rife2/bld-property-file")
-                .developer(new PublishDeveloper().id("ethauvin").name("Erik C. Thauvin").email("erik@thauvin.net")
+                .developer(
-                        .url("https://erik.thauvin.net/"))
+                        new PublishDeveloper().id("ethauvin")
-                .developer(new PublishDeveloper().id("gbevin").name("Geert Bevin").email("gbevin@uwyn.com")
+                                .name("Erik C. Thauvin")
-                        .url("https://github.com/gbevin"))
+                                .email("erik@thauvin.net")
-                .license(new PublishLicense().name("The Apache License, Version 2.0")
+                                .url("https://erik.thauvin.net/")
-                        .url("http://www.apache.org/licenses/LICENSE-2.0.txt"))
+                )
-                .scm(new PublishScm().connection("scm:git:https://github.com/rife2/bld-property-file.git")
+                .developer(
-                        .developerConnection("scm:git:git@github.com:rife2/bld-property-file.git")
+                        new PublishDeveloper()
-                        .url("https://github.com/rife2/bld-property-file"))
+                                .id("gbevin")
+                                .name("Geert Bevin")
+                                .email("gbevin@uwyn.com")
+                                .url("https://github.com/gbevin")
+                )
+                .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-property-file.git")
+                                .developerConnection("scm:git:git@github.com:rife2/bld-property-file.git")
+                                .url("https://github.com/rife2/bld-property-file"))
                 .signKey(property("sign.key"))
                 .signPassphrase(property("sign.passphrase"));
     }

src/main/java/rife/bld/extension/propertyfile/Calc.java

@@ -26,7 +26,13 @@ import java.util.function.IntFunction;
  * @since 1.0
  */
 public final class Calc {
+    /**
+     * The add function.
+     */
     public static final IntFunction<Integer> ADD = Calc::add;
+    /**
+     * The sub function.
+     */
     public static final IntFunction<Integer> SUB = Calc::sub;
 
 
@@ -38,6 +44,7 @@ public final class Calc {
      * Adds {@code 1} to the value.
      *
      * @param v the value
+     * @return the new value
      */
     public static Integer add(int v) {
         return v + 1;
@@ -47,6 +54,7 @@ public final class Calc {
      * Subtracts {@code 1} to the value.
      *
      * @param v the value
+     * @return the new value
      */
     public static Integer sub(int v) {
         return v - 1;

src/main/java/rife/bld/extension/propertyfile/Entry.java

@@ -26,6 +26,11 @@ import java.util.function.BiFunction;
  * @since 1.0
  */
 public class Entry extends EntryBase {
+    /**
+     * Instantiates a new Entry.
+     *
+     * @param key the key
+     */
     public Entry(String key) {
         super(key);
     }
@@ -34,6 +39,7 @@ public class Entry extends EntryBase {
      * <p>Sets the initial value to set the {@link java.util.Properties property} to, if not already defined.</p>
      *
      * @param defaultValue the default value
+     * @return the entry
      */
     @SuppressWarnings("unused")
     public Entry defaultValue(Object defaultValue) {
@@ -43,6 +49,8 @@ public class Entry extends EntryBase {
 
     /**
      * Sets the {@link Entry entry} up for deletion.
+     *
+     * @return the entry
      */
     public Entry delete() {
         setDelete(true);
@@ -53,6 +61,7 @@ public class Entry extends EntryBase {
      * Creates a new {@link Entry entry}.
      *
      * @param modify the modification function
+     * @return the entry
      */
     public Entry modify(BiFunction<String, String, String> modify) {
         setModify(modify);
@@ -64,6 +73,7 @@ public class Entry extends EntryBase {
      *
      * @param value  the value to perform a modification with
      * @param modify the modification function
+     * @return the entry
      */
     public Entry modify(String value, BiFunction<String, String, String> modify) {
         setModifyValue(value);
@@ -75,6 +85,7 @@ public class Entry extends EntryBase {
      * Sets the new {@link java.util.Properties property} value.
      *
      * @param s The new value
+     * @return the entry
      */
     public Entry set(Object s) {
         setNewValue(s);

src/main/java/rife/bld/extension/propertyfile/EntryBase.java

@@ -49,6 +49,8 @@ public class EntryBase {
 
     /**
      * Returns the calculation function.
+     *
+     * @return the calc function
      */
     protected IntFunction<Integer> getCalc() {
         return calc;
@@ -56,6 +58,8 @@ public class EntryBase {
 
     /**
      * Returns the default value.
+     *
+     * @return the default value
      */
     protected Object getDefaultValue() {
         return defaultValue;
@@ -63,6 +67,8 @@ public class EntryBase {
 
     /**
      * Returns the key of the {@link java.util.Properties property}.
+     *
+     * @return the key
      */
     protected String getKey() {
         return key;
@@ -70,6 +76,8 @@ public class EntryBase {
 
     /**
      * Returns the modify function.
+     *
+     * @return the modify function
      */
     protected BiFunction<String, String, String> getModify() {
         return modify;
@@ -77,6 +85,8 @@ public class EntryBase {
 
     /**
      * Returns the value to be used in the {@link #modify} function.
+     *
+     * @return the modify value
      */
     protected String getModifyValue() {
         return modifyValue;
@@ -84,6 +94,8 @@ public class EntryBase {
 
     /**
      * Returns the new value to set the {@link java.util.Properties property)} to.
+     *
+     * @return the new value
      */
     public Object getNewValue() {
         return newValue;
@@ -91,6 +103,8 @@ public class EntryBase {
 
     /**
      * Returns the pattern.
+     *
+     * @return the pattern
      */
     protected String getPattern() {
         return pattern;
@@ -98,6 +112,8 @@ public class EntryBase {
 
     /**
      * Returns the {@link EntryDate.Units unit}.
+     *
+     * @return the unit
      */
     protected EntryDate.Units getUnit() {
         return unit;
@@ -105,6 +121,8 @@ public class EntryBase {
 
     /**
      * Returns {@code true} if the {@link java.util.Properties property} is to be deleted.
+     *
+     * @return {@code true} or {@code false}
      */
     protected boolean isDelete() {
         return isDelete;
@@ -114,6 +132,7 @@ public class EntryBase {
      * Sets the key of the {@link java.util.Properties property}.
      *
      * @param key the {@link java.util.Properties property} key
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public EntryBase key(String key) {
@@ -123,6 +142,8 @@ public class EntryBase {
 
     /**
      * Sets the calculation function.
+     *
+     * @param calc the calc function
      */
     protected void setCalc(IntFunction<Integer> calc) {
         this.calc = calc;
@@ -139,6 +160,8 @@ public class EntryBase {
 
     /**
      * Sets whether the {@link java.util.Properties property} should be deleted.
+     *
+     * @param delete {@code true} or {@code false}
      */
     protected void setDelete(boolean delete) {
         isDelete = delete;
@@ -155,6 +178,8 @@ public class EntryBase {
 
     /**
      * Sets the modify function.
+     *
+     * @param modify the modify function
      */
     protected void setModify(BiFunction<String, String, String> modify) {
         this.modify = modify;
@@ -163,7 +188,8 @@ public class EntryBase {
     /**
      * Sets the modify function.
      *
-     * @param value the value to perform a modification with
+     * @param value  the value to perform a modification with
+     * @param modify the modify function
      */
     protected void setModify(String value, BiFunction<String, String, String> modify) {
         this.modifyValue = value;

src/main/java/rife/bld/extension/propertyfile/EntryDate.java

@@ -41,6 +41,7 @@ public class EntryDate extends EntryBase {
      * Creates a new {@link EntryDate entry}.
      *
      * @param calc the calculation function
+     * @return this instance
      */
     public EntryDate calc(IntFunction<Integer> calc) {
         setCalc(calc);
@@ -49,6 +50,8 @@ public class EntryDate extends EntryBase {
 
     /**
      * Sets the {@link EntryDate entry} up for deletion.
+     *
+     * @return this instance
      */
     public EntryDate delete() {
         setDelete(true);
@@ -57,6 +60,8 @@ public class EntryDate extends EntryBase {
 
     /**
      * Sets the new {@link java.util.Properties property} value to now.
+     *
+     * @return this instance
      */
     public EntryDate now() {
         setNewValue("now");
@@ -68,6 +73,7 @@ public class EntryDate extends EntryBase {
      * {@link java.time.format.DateTimeFormatter DateTimeFormatter} respectively.
      *
      * @param pattern the pattern
+     * @return this instance
      */
     public EntryDate pattern(String pattern) {
         setPattern(pattern);
@@ -78,6 +84,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to an {@link Instant}
      *
      * @param instant the {@link Instant} to set the value to
+     * @return this instance
      */
     public EntryDate set(Instant instant) {
         setNewValue(instant);
@@ -88,6 +95,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link LocalDate}
      *
      * @param date the {@link LocalDate} to set the value to
+     * @return this instance
      */
     public EntryDate set(LocalDate date) {
         setNewValue(date);
@@ -98,6 +106,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link LocalDateTime}
      *
      * @param date the {@link LocalDateTime} to set the value to
+     * @return this instance
      */
     public EntryDate set(LocalDateTime date) {
         setNewValue(date);
@@ -108,6 +117,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link ZonedDateTime}
      *
      * @param date the {@link ZonedDateTime} to set the value to
+     * @return this instance
      */
     public EntryDate set(ZonedDateTime date) {
         setNewValue(date);
@@ -118,6 +128,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link LocalTime}
      *
      * @param time the {@link LocalTime} to set the value to
+     * @return this instance
      */
     public EntryDate set(LocalTime time) {
         setNewValue(time);
@@ -128,6 +139,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link Calendar}
      *
      * @param cal the {@link Calendar} to set the value to
+     * @return this instance
      */
     public EntryDate set(Calendar cal) {
         setNewValue(cal);
@@ -138,6 +150,7 @@ public class EntryDate extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to a {@link Date}
      *
      * @param date the {@link Date} to set the value to
+     * @return this instance
      */
     public EntryDate set(Date date) {
         setNewValue(date);
@@ -148,6 +161,7 @@ public class EntryDate extends EntryBase {
      * Sets the {@link Units unit} value to apply to calculations for {@link EntryDate}.
      *
      * @param unit the {@link Units unit}
+     * @return this instance
      */
     public EntryDate unit(Units unit) {
         setUnit(unit);
@@ -168,6 +182,33 @@ public class EntryDate extends EntryBase {
      * </uL>
      */
     public enum Units {
-        SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR
+        /**
+         * Second units.
+         */
+        SECOND,
+        /**
+         * Minute units.
+         */
+        MINUTE,
+        /**
+         * Hour units.
+         */
+        HOUR,
+        /**
+         * Day units.
+         */
+        DAY,
+        /**
+         * Week units.
+         */
+        WEEK,
+        /**
+         * Month units.
+         */
+        MONTH,
+        /**
+         * Year units.
+         */
+        YEAR
     }
 }

src/main/java/rife/bld/extension/propertyfile/EntryInt.java

@@ -38,6 +38,7 @@ public class EntryInt extends EntryBase {
      * Creates a new {@link EntryInt entry}.
      *
      * @param calc the calculation function.
+     * @return this instance
      */
     public EntryInt calc(IntFunction<Integer> calc) {
         setCalc(calc);
@@ -48,6 +49,7 @@ public class EntryInt extends EntryBase {
      * Sets the initial value to set the {@link java.util.Properties property} to, if not already defined.
      *
      * @param defaultValue the default value
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public EntryInt defaultValue(Object defaultValue) {
@@ -57,6 +59,8 @@ public class EntryInt extends EntryBase {
 
     /**
      * Sets the {@link EntryInt entry} up for deletion.
+     *
+     * @return this instance
      */
     public EntryInt delete() {
         setDelete(true);
@@ -67,6 +71,7 @@ public class EntryInt extends EntryBase {
      * Sets the new {@link java.util.Properties property} value to an integer.
      *
      * @param i The integer to set the value to
+     * @return this instance
      */
     public EntryInt set(int i) {
         setNewValue(i);

src/main/java/rife/bld/extension/propertyfile/PropertyFileOperation.java

@@ -41,6 +41,7 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
      * Sets the comment to be inserted at the top of the {@link java.util.Properties} file.
      *
      * @param comment the header comment
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public PropertyFileOperation comment(String comment) {
@@ -53,6 +54,7 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
      * file.
      *
      * @param entry the {@link Entry entry}
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public PropertyFileOperation entry(EntryBase entry) {
@@ -112,6 +114,7 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
      * Sets the {@link #execute() execution} to return a failure on any warnings.
      *
      * @param failOnWarning if set to {@code true}, the execution will fail on any warnings.
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public PropertyFileOperation failOnWarning(boolean failOnWarning) {
@@ -123,6 +126,7 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
      * Sets the location of the {@link java.util.Properties} file to be edited.
      *
      * @param file the file to be edited
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public PropertyFileOperation file(File file) {
@@ -134,6 +138,7 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
      * Sets the location of the {@link java.util.Properties} file to be edited.
      *
      * @param file the file to be edited
+     * @return this instance
      */
     @SuppressWarnings("unused")
     public PropertyFileOperation file(String file) {
@@ -143,6 +148,9 @@ public class PropertyFileOperation extends AbstractOperation<PropertyFileOperati
 
     /**
      * Creates a new operation.
+     *
+     * @param project the project
+     * @return this instance
      */
     public PropertyFileOperation fromProject(BaseProject project) {
         this.project = project;

src/main/java/rife/bld/extension/propertyfile/PropertyFileUtils.java

@@ -48,8 +48,9 @@ public final class PropertyFileUtils {
      * Returns the new value, value or default value depending on which is specified.
      *
      * @param value        the value
-     * @param newValue     the new value
      * @param defaultValue the default value
+     * @param newValue     the new value
+     * @return the object
      */
     public static Object currentValue(String value, Object defaultValue, Object newValue) {
         if (newValue != null) {
@@ -67,6 +68,8 @@ public final class PropertyFileUtils {
      * @param command the issuing command
      * @param file    the file location
      * @param p       the {@link Properties properties} to load into.
+     * @return the boolean
+     * @throws Exception the exception
      */
     @SuppressWarnings("PMD.SignatureDeclareThrowsException")
     public static boolean loadProperties(String command, File file, Properties p) throws Exception {
@@ -90,9 +93,12 @@ public final class PropertyFileUtils {
     /**
      * Processes a date {@link Properties property}.
      *
-     * @param command the issuing command
+     * @param command       the issuing command
-     * @param p       the {@link Properties property}
+     * @param p             the {@link Properties property}
-     * @param entry   the {@link Entry} containing the {@link Properties property} edits
+     * @param entry         the {@link Entry} containing the {@link Properties property} edits
+     * @param failOnWarning the fail on warning
+     * @return the boolean
+     * @throws Exception the exception
      */
     @SuppressWarnings({"PMD.SignatureDeclareThrowsException", "PMD.ExceptionAsFlowControl"})
     public static boolean processDate(String command, Properties p, EntryDate entry, boolean failOnWarning)
@@ -192,9 +198,12 @@ public final class PropertyFileUtils {
     /**
      * Processes an integer {@link Properties property}.
      *
-     * @param command the issuing command
+     * @param command       the issuing command
-     * @param p       the {@link Properties property}
+     * @param p             the {@link Properties property}
-     * @param entry   the {@link Entry} containing the {@link Properties property} edits
+     * @param entry         the {@link Entry} containing the {@link Properties property} edits
+     * @param failOnWarning the fail on warning
+     * @return the boolean
+     * @throws Exception the exception
      */
     @SuppressWarnings("PMD.SignatureDeclareThrowsException")
     public static boolean processInt(String command, Properties p, EntryInt entry, boolean failOnWarning)
@@ -228,6 +237,7 @@ public final class PropertyFileUtils {
      *
      * @param p     the {@link Properties property}
      * @param entry the {@link Entry} containing the {@link Properties property} edits
+     * @return the boolean
      */
     public static boolean processString(Properties p, Entry entry) {
         var value = currentValue(p.getProperty(entry.getKey()), entry.getDefaultValue(), entry.getNewValue());
@@ -247,6 +257,7 @@ public final class PropertyFileUtils {
      * @param file    the file location
      * @param comment the header comment
      * @param p       the {@link Properties} to save into the file
+     * @throws IOException the io exception
      */
     public static void saveProperties(File file, String comment, Properties p) throws IOException {
         try (var output = Files.newOutputStream(file.toPath())) {
@@ -275,6 +286,7 @@ public final class PropertyFileUtils {
      * @param message       the message log
      * @param e             the related exception
      * @param failOnWarning logs and throws exception if set to {@code true}
+     * @throws Exception the exception
      */
     @SuppressWarnings({"PMD.SignatureDeclareThrowsException"})
     static void warn(String command, String message, Exception e, boolean failOnWarning) throws Exception {