ARTEMIS-5314 overhaul JavaDoc formatting & content

This commit overhauls JavaDoc formatting & content across the entire
code-base placing a heavy emphasis on the don't-repeat-yourself
principle (i.e. DRY).

The main goals here are readability, conciseness, and safeguarding
future commits from the same kinds of mistakes that have plagued the
code-base for many years now.

It includes the following changes:

 - Remove empty @param, @throws, & @return tags.
 - Remove useless/boilerplate comments.
 - Re-wrap to 120 characters. Many comments already used this limit
   while others were less than and still other were more than this
   limit. Using 120 was a happy medium.
 - Enforce multi-line syntax, e.g.:
   /**
    * Lorem ipsum
    */
 - Change /** to /* where appropriate (e.g. license headers,
   intra-method comments, etc.)
 - Change /* to /** where appropriate (e.g. method descriptions,
   comments using tags like @code, etc.)
 - Remove trailing or extraneous '*' characters.
 - Remove JavaDocs from implementations when the JavaDocs of the
   interface will suffice.
 - Use {@code Lorem ipsum} syntax where appropriate.
 - Use <p> for empty lines. Remove <br>, <br/>, & <br />
 - Use the {@return ...} sytanx introduced in Java 16. Details are at
   https://bugs.openjdk.org/browse/JDK-8256804.
 - Align @param descriptions.
 - Align @throws descriptions.
 - Add empty line between description and start of tags (e.g. @param).
 - Fix the prolific "whether or not" to the more correct just "whether".
 - Enforce many of these standards via checkstyle.
 - Remove references to defunct issue trackers or forums.
 - Convert single line comments using /* syntax to use //.

Author: jbertram

artemis-boot/src/main/java/org/apache/activemq/artemis/boot/Artemis.java

@@ -28,10 +28,7 @@
 import java.util.List;
 
 /**
- * <p>
- * A main class which setups up a classpath and then passes
- * execution off to the ActiveMQ Artemis cli main.
- * </p>
+ * A main class which setups up a classpath and then passes execution off to the ActiveMQ Artemis cli main.
  */
 public class Artemis {
 

artemis-cdi-client/src/main/java/org/apache/artemis/client/cdi/configuration/ArtemisClientConfiguration.java

@@ -28,12 +28,12 @@ public interface ArtemisClientConfiguration {
    String REMOTE_CONNECTOR = NettyConnectorFactory.class.getName();
 
    /**
-    * @return if present, sends a username for the connection
+    * {@return if present, sends a username for the connection}
     */
    String getUsername();
 
    /**
-    * @return the password for the connection.  If username is set, password must be set
+    * {@return the password for the connection.  If username is set, password must be set}
     */
    String getPassword();
 
@@ -45,32 +45,32 @@ public interface ArtemisClientConfiguration {
    String getUrl();
 
    /**
-    * @return The hostname to connect to
+    * {@return The hostname to connect to}
     */
    String getHost();
 
    /**
-    * @return the port number to connect to
+    * {@return the port number to connect to}
     */
    Integer getPort();
 
    /**
-    * @return the connector factory to use for connections.
+    * {@return the connector factory to use for connections}
     */
    String getConnectorFactory();
 
    /**
-    * @return Whether or not to start the embedded broker
+    * {@return whether to start the embedded broker}
     */
    boolean startEmbeddedBroker();
 
    /**
-    * @return whether or not this is an HA connection
+    * {@return whether this is an HA connection}
     */
    boolean isHa();
 
    /**
-    * @return whether or not the authentication parameters should be used
+    * {@return whether the authentication parameters should be used}
     */
    boolean hasAuthentication();
 }

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/Artemis.java

@@ -62,14 +62,13 @@
 
 /**
  * Artemis is the main CLI entry point for managing/running a broker.
- *
- * Want to start or debug a broker from an IDE?  This is probably the best class to
- * run.  Make sure set the -Dartemis.instance=path/to/instance system property.
- * You should also use the 'apache-artemis' module for the class path since that
- * includes all artemis modules.
- *
- * Notice that this class should not use any logging as it's part of the bootstrap and using logging here could
- *        disrupt the order of bootstrapping on certain components (e.g. JMX being started from log4j)
+ * <p>
+ * Want to start or debug a broker from an IDE?  This is probably the best class to run.  Make sure set the
+ * -Dartemis.instance=path/to/instance system property. You should also use the 'apache-artemis' module for the class
+ * path since that includes all artemis modules.
+ * <p>
+ * Notice that this class should not use any logging as it's part of the bootstrap and using logging here could disrupt
+ * the order of bootstrapping on certain components (e.g. JMX being started from log4j)
  */
 @Command(name = "artemis", description = "ActiveMQ Artemis Command Line")
 public class Artemis implements Runnable {
@@ -194,8 +193,7 @@ public static Object execute(boolean inputEnabled, boolean useSystemOut, boolean
    }
 
    /**
-    * This method is used to validate exception returns.
-    * Useful on test cases
+    * This method is used to validate exception returns. Useful on test cases.
     */
    private static Object internalExecute(boolean shellEnabled, File artemisHome, File artemisInstance, File etcFolder, String[] args) throws Exception {
       return internalExecute(shellEnabled, artemisHome, artemisInstance, etcFolder, args, new ActionContext());

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/ActionAbstract.java

@@ -82,9 +82,11 @@ public void setHomeValues(File brokerHome, File brokerInstance, File etcFolder)
    @Override
    public String getBrokerInstance() {
       if (brokerInstance == null) {
-         /* We use File URI for locating files.  The ARTEMIS_HOME variable is used to determine file paths.  For Windows
-         the ARTEMIS_HOME variable will include back slashes (An invalid file URI character path separator).  For this
-         reason we overwrite the ARTEMIS_HOME variable with backslashes replaced with forward slashes. */
+         /*
+          * We use File URI for locating files.  The ARTEMIS_HOME variable is used to determine file paths. For Windows
+          * the ARTEMIS_HOME variable will include back slashes (An invalid file URI character path separator). For this
+          * reason we overwrite the ARTEMIS_HOME variable with backslashes replaced with forward slashes.
+          */
          brokerInstance = System.getProperty("artemis.instance");
          if (brokerInstance != null) {
             brokerInstance = brokerInstance.replace("\\", "/");
@@ -188,9 +190,11 @@ public URI getBrokerURIInstance() {
    @Override
    public String getBrokerHome() {
       if (brokerHome == null) {
-         /* We use File URI for locating files.  The ARTEMIS_HOME variable is used to determine file paths.  For Windows
-         the ARTEMIS_HOME variable will include back slashes (An invalid file URI character path separator).  For this
-         reason we overwrite the ARTEMIS_HOME variable with backslashes replaced with forward slashes. */
+         /*
+          * We use File URI for locating files.  The ARTEMIS_HOME variable is used to determine file paths. For Windows
+          * the ARTEMIS_HOME variable will include back slashes (An invalid file URI character path separator). For this
+          * reason we overwrite the ARTEMIS_HOME variable with backslashes replaced with forward slashes.
+          */
          brokerHome = System.getProperty("artemis.home");
          if (brokerHome != null) {
             brokerHome = brokerHome.replace("\\", "/");

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/Configurable.java

@@ -34,7 +34,7 @@
 import picocli.CommandLine.Parameters;
 
 /**
- * Abstract class where we can replace the configuration in various places *
+ * Abstract class where we can replace the configuration in various places
  */
 public abstract class Configurable extends ActionAbstract {
 

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/InputAbstract.java

@@ -28,8 +28,9 @@ public class InputAbstract extends ActionAbstract {
    private static boolean inputEnabled = false;
 
    /**
-    * Test cases validating or using the CLI cannot deal with inputs,
-    * so they are generally disabled, however the main method from the CLI will enable it back. */
+    * Test cases validating or using the CLI cannot deal with inputs, so they are generally disabled, however the main
+    * method from the CLI will enable it back.
+    */
    public static void enableInput() {
       inputEnabled = true;
    }

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/Run.java

@@ -61,10 +61,8 @@ public class Run extends LockAbstract {
    private Timer shutdownTimer;
 
    /**
-    * This will disable the System.exit at the end of the server.stop, as that means there are other things
-    * happening on the same VM.
-    *
-    * @param embedded
+    * This will disable the System.exit at the end of the server.stop, as that means there are other things happening on
+    * the same VM.
     */
    public static void setEmbedded(boolean embedded) {
       Run.embedded = true;
@@ -164,8 +162,6 @@ public void deActivate() {
 
    /**
     * Add a simple shutdown hook to stop the server.
-    *
-    * @param configurationDir
     */
    private void addShutdownHook(File configurationDir) {
 

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/helper/HelperCreate.java

@@ -30,8 +30,10 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-/** This is a class simulating what the Artemis Maven Plugin does.
- *  You may use by creating a new instance, filling the properties, and calling the method create */
+/**
+ * This is a class simulating what the Artemis Maven Plugin does. You may use by creating a new instance, filling the
+ * properties, and calling the method create
+ */
 public class HelperCreate extends HelperBase {
 
    public HelperCreate(String homeProperty) {
@@ -76,9 +78,6 @@ public HelperCreate(File artemisHome) {
 
    private boolean failoverOnShutdown = false;
 
-   /**
-    * it will disable auto-tune
-    */
    private boolean noAutoTune = true;
 
    private String messageLoadBalancing = "ON_DEMAND";
@@ -384,5 +383,4 @@ private void copyConfigurationFiles(String[] list,
          }
       }
    }
-
 }

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/messages/perf/AsyncJms2ProducerFacade.java

@@ -132,8 +132,8 @@ private void addedPendingSend() {
    }
 
    /**
-    * if {@code true}, a subsequent {@link #trySend} would return {@link SendAttemptResult#Success}.<br>
-    * Otherwise, a subsequent {@link #trySend} would return {@link SendAttemptResult#NotAvailable}.
+    * If {@code true}, a subsequent {@link #trySend} would return {@link SendAttemptResult#Success}. Otherwise, a
+    * subsequent {@link #trySend} would return {@link SendAttemptResult#NotAvailable}.
     */
    private boolean isAvailable() {
       if (maxPending > 0 && pending == maxPending) {

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/messages/perf/PaddingDecimalFormat.java

@@ -26,8 +26,8 @@ public class PaddingDecimalFormat extends DecimalFormat {
    private final StringBuilder pad;
 
    /**
-    * Creates a PaddingDecimalFormat using the given pattern and minimum {@code minLength} and the symbols for the default
-    * locale.
+    * Creates a PaddingDecimalFormat using the given pattern and minimum {@code minLength} and the symbols for the
+    * default locale.
     */
    public PaddingDecimalFormat(String pattern, int minLength) {
       super(pattern);