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

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);

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

@@ -430,16 +430,10 @@ private static class PageCursorsInfo {
       private PageCursorsInfo() {
       }
 
-      /**
-       * @return the pgTXs
-       */
       Set<Long> getPgTXs() {
          return pgTXs;
       }
 
-      /**
-       * @return the cursorRecords
-       */
       Map<Long, Set<PagePosition>> getCursorRecords() {
          return cursorRecords;
       }

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/tools/xml/XMLMessageExporter.java

@@ -31,7 +31,9 @@
 import org.apache.activemq.artemis.reader.TextMessageUtil;
 
 
-/** This is an Utility class that will import the outputs in XML format. */
+/**
+ * This is an Utility class that will import the outputs in XML format.
+ */
 public class XMLMessageExporter {
 
    private static final int LARGE_MESSAGE_CHUNK_SIZE = 1000;

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/tools/xml/XMLMessageImporter.java

@@ -37,7 +37,9 @@
 import org.slf4j.LoggerFactory;
 import java.lang.invoke.MethodHandles;
 
-/** This is an Utility class that will import the outputs in XML format. */
+/**
+ * This is an Utility class that will import the outputs in XML format.
+ */
 public class XMLMessageImporter {
 
    private static final Logger logger = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
@@ -236,7 +238,7 @@ private void processMessageBody(final ICoreMessage message, boolean decodeTextMe
     * to be combined to reconstruct the Base64 encoded string.  You can't decode bits and pieces of each CDATA.  Each
     * CDATA has to be decoded in its entirety.
     *
-    * @param processor used to deal with the decoded CDATA elements
+    * @param processor         used to deal with the decoded CDATA elements
     * @param decodeTextMessage If this a text message we decode UTF8 and encode as a simple string
     */
    private void getMessageBodyBytes(MessageBodyBytesProcessor processor, boolean decodeTextMessage) throws IOException, XMLStreamException {
@@ -247,7 +249,8 @@ private void getMessageBodyBytes(MessageBodyBytesProcessor processor, boolean de
          if (currentEventType == XMLStreamConstants.END_ELEMENT) {
             break;
          } else if (currentEventType == XMLStreamConstants.CHARACTERS && reader.isWhiteSpace() && !cdata.isEmpty()) {
-            /* when we hit a whitespace CHARACTERS event we know that the entire CDATA is complete so decode, pass back to
+            /*
+             * when we hit a whitespace CHARACTERS event we know that the entire CDATA is complete so decode, pass back to
              * the processor, and reset the cdata for the next event(s)
              */
             if (decodeTextMessage) {

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/tools/xml/XmlDataConstants.java

@@ -17,8 +17,8 @@
 package org.apache.activemq.artemis.cli.commands.tools.xml;
 
 /**
- * The constants shared by <code>org.apache.activemq.tools.XmlDataImporter</code> and
- * <code>org.apache.activemq.tools.XmlDataExporter</code>.
+ * The constants shared by {@code org.apache.activemq.tools.XmlDataImporter} and
+ * {@code org.apache.activemq.tools.XmlDataExporter}.
  */
 public final class XmlDataConstants {
 

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/tools/xml/XmlDataExporter.java

@@ -130,13 +130,6 @@ public Object execute(ActionContext context) throws Exception {
 
    /**
     * Use setConfiguration and process(out) instead.
-    *
-    * @param out
-    * @param bindingsDir
-    * @param journalDir
-    * @param pagingDir
-    * @param largeMessagesDir
-    * @throws Exception
     */
    @Deprecated
    public void process(OutputStream out,
@@ -409,9 +402,10 @@ private void printSingleMessageAsXML(ICoreMessage message, List<String> queues)
       exporter.printSingleMessageAsXML(message, queues, false);
       messagesPrinted++;
    }
+
    /**
-    * Reads from the page files and prints messages as it finds them (making sure to check acks and transactions
-    * from the journal).
+    * Reads from the page files and prints messages as it finds them (making sure to check acks and transactions from
+    * the journal).
     */
    private void printPagedMessagesAsXML() {
       try {
@@ -509,7 +503,7 @@ private List<String> extractQueueNames(Map<Long, DescribeJournal.ReferenceDescri
    }
 
    /**
-    * Proxy to handle indenting the XML since <code>javax.xml.stream.XMLStreamWriter</code> doesn't support that.
+    * Proxy to handle indenting the XML since {@code javax.xml.stream.XMLStreamWriter} doesn't support that.
     */
    public static class PrettyPrintHandler implements InvocationHandler {
 

artemis-cli/src/main/java/org/apache/activemq/artemis/cli/commands/tools/xml/XmlDataImporter.java

@@ -64,9 +64,9 @@
 import picocli.CommandLine.Option;
 
 /**
- * Read XML output from <code>org.apache.activemq.artemis.core.persistence.impl.journal.XmlDataExporter</code>, create a core session, and
- * send the messages to a running instance of ActiveMQ Artemis.  It uses the StAX <code>javax.xml.stream.XMLStreamReader</code>
- * for speed and simplicity.
+ * Read XML output from {@code org.apache.activemq.artemis.core.persistence.impl.journal.XmlDataExporter}, create a core
+ * session, and send the messages to a running instance of ActiveMQ Artemis.  It uses the StAX
+ * {@code javax.xml.stream.XMLStreamReader} for speed and simplicity.
  */
 @Command(name = "imp", description = "Import all message-data using an XML that could be interpreted by any system.")
 public final class XmlDataImporter extends ConnectionConfigurationAbtract {
@@ -130,9 +130,9 @@ public void process(String inputFileName, String host, int port) throws Exceptio
 
    /**
     * This is the normal constructor for programmatic access to the
-    * <code>org.apache.activemq.artemis.core.persistence.impl.journal.XmlDataImporter</code> if the session passed
-    * in uses auto-commit for sends.
-    * <br>
+    * {@code org.apache.activemq.artemis.core.persistence.impl.journal.XmlDataImporter} if the session passed in uses
+    * auto-commit for sends.
+    * <p>
     * If the session needs to be transactional then use the constructor which takes 2 sessions.
     *
     * @param inputStream the stream from which to read the XML for import
@@ -144,9 +144,9 @@ public void process(InputStream inputStream, ClientSession session) throws Excep
 
    /**
     * This is the constructor to use if you wish to import all messages transactionally.
-    * <br>
-    * Pass in a session which doesn't use auto-commit for sends, and one that does (for management
-    * operations necessary during import).
+    * <p>
+    * Pass in a session which doesn't use auto-commit for sends, and one that does (for management operations necessary
+    * during import).
     *
     * @param inputStream       the stream from which to read the XML for import
     * @param session           used for sending messages, doesn't need to auto-commit sends
@@ -511,6 +511,4 @@ private void bindAddress() throws Exception {
          logger.debug("Binding {} already exists so won't re-bind.", addressName);
       }
    }
-
-
 }

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

@@ -23,7 +23,7 @@
 
 /**
  * Adding a new user, example:
- * ./artemis user add --user-command-user guest --role admin --user-command-password ***
+ * {@literal ./artemis user add --user-command-user guest --role admin --user-command-password ***}
  */
 @Command(name = "add", description = "Add a user.")
 public class AddUser extends PasswordAction {

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

@@ -22,7 +22,9 @@
 
 /**
  * Remove a user, example:
+ * <pre>{@code
  * ./artemis user rm --user guest
+ * }</pre>
  */
 @Command(name = "rm", description = "Remove an existing user.")
 public class RemoveUser extends UserAction {