Added lots of javadoc

src/main/java/net/openhft/chronicle/queue/BufferMode.java

@@ -18,10 +18,26 @@
 
 package net.openhft.chronicle.queue;
 
+/**
+ * Enum representing the different buffer modes that can be used within Chronicle Queue.
+ * Each mode has a specific use case and behavior depending on the configuration.
+ */
 public enum BufferMode {
-    None,    // The default
+    /**
+     * The default buffer mode.
+     * No additional buffering or special handling is applied.
+     */
+    None,
 
-    Copy,    //  used in conjunction with encryption
+    /**
+     * Buffer mode used in conjunction with encryption.
+     * Data is copied into a buffer before being processed.
+     */
+    Copy,
 
-    Asynchronous   // used by chronicle-ring [ which is an enterprise product ]
+    /**
+     * Buffer mode used for asynchronous processing.
+     * This mode is specific to Chronicle Ring, an enterprise product.
+     */
+    Asynchronous
 }

src/main/java/net/openhft/chronicle/queue/ChronicleHistoryReaderMain.java

@@ -19,28 +19,45 @@
 package net.openhft.chronicle.queue;
 
 import net.openhft.chronicle.queue.reader.ChronicleHistoryReader;
+import net.openhft.chronicle.wire.MessageHistory;
 import org.apache.commons.cli.*;
 import org.jetbrains.annotations.NotNull;
 
 import java.io.PrintWriter;
 import java.nio.file.Paths;
+import java.util.Arrays;
 import java.util.concurrent.TimeUnit;
 
 /**
- * Reads @see MessageHistory from a chronicle and outputs histograms for
+ * The main class for reading {@link MessageHistory} from a Chronicle queue
+ * and generating histograms for:
  * <ul>
- * <li>latencies for each component that has processed a message</li>
- * <li>latencies between each component that has processed a message</li>
+ *     <li>Latencies for each component that has processed a message</li>
+ *     <li>Latencies between each component that has processed a message</li>
  * </ul>
- *
- * @author Jerry Shea
+ * This class provides options to configure the reader via command line arguments and outputs the results
+ * to the console.
  */
 public class ChronicleHistoryReaderMain {
 
+    private static final int HELP_OUTPUT_LINE_WIDTH = 180;
+
+    /**
+     * Entry point of the application.
+     * Initializes the {@link ChronicleHistoryReaderMain} and passes command-line arguments.
+     *
+     * @param args Command-line arguments
+     */
     public static void main(@NotNull String[] args) {
         new ChronicleHistoryReaderMain().run(args);
     }
 
+    /**
+     * Runs the ChronicleHistoryReader setup and execution.
+     * Parses command-line options and configures the {@link ChronicleHistoryReader}.
+     *
+     * @param args Command-line arguments
+     */
     protected void run(String[] args) {
         final Options options = options();
         final CommandLine commandLine = parseCommandLine(args, options);
@@ -51,6 +68,12 @@ protected void run(String[] args) {
         }
     }
 
+    /**
+     * Configures the {@link ChronicleHistoryReader} based on the command-line options.
+     *
+     * @param commandLine Parsed command-line options
+     * @param chronicleHistoryReader The history reader to configure
+     */
     protected void setup(@NotNull final CommandLine commandLine, @NotNull final ChronicleHistoryReader chronicleHistoryReader) {
         chronicleHistoryReader.
                 withMessageSink(System.out::println).
@@ -67,36 +90,65 @@ protected void setup(@NotNull final CommandLine commandLine, @NotNull final Chro
             chronicleHistoryReader.withSummaryOutput(Integer.parseInt(commandLine.getOptionValue('u')));
     }
 
+    /**
+     * Initializes a new instance of {@link ChronicleHistoryReader}.
+     *
+     * @return A new {@link ChronicleHistoryReader} instance
+     */
     @NotNull
     protected ChronicleHistoryReader chronicleHistoryReader() {
         return new ChronicleHistoryReader();
     }
 
+    /**
+     * Parses command-line arguments using Apache Commons CLI.
+     * If help is requested, it prints the help message and exits.
+     *
+     * @param args    Command-line arguments
+     * @param options Available command-line options
+     * @return Parsed {@link CommandLine} object
+     */
     protected CommandLine parseCommandLine(@NotNull final String[] args, final Options options) {
-        final CommandLineParser parser = new DefaultParser();
+        final CommandLineParser parser = new DefaultParser(); // Initialize command-line parser
         CommandLine commandLine = null;
         try {
             commandLine = parser.parse(options, args);
 
+            // If help option is selected, print help and exit
             if (commandLine.hasOption('h')) {
                 printHelpAndExit(options, 0);
             }
         } catch (ParseException e) {
-            printHelpAndExit(options, 1, e.getMessage());
+            // If parsing fails, print help with an error message and exit
+            String cmdLine = Arrays.toString(args);
+            printHelpAndExit(options, "[-h]".equals(cmdLine) ? 0 : 1, e.getMessage());
         }
 
         return commandLine;
     }
 
+    /**
+     * Prints help and exits the program.
+     *
+     * @param options Command-line options
+     * @param status  Exit status
+     */
     protected void printHelpAndExit(final Options options, int status) {
         printHelpAndExit(options, status, null);
     }
 
+    /**
+     * Prints help and exits the program, optionally with a message.
+     *
+     * @param options Command-line options
+     * @param status  Exit status
+     * @param message Optional message to print before help
+     */
     protected void printHelpAndExit(final Options options, int status, String message) {
         final PrintWriter writer = new PrintWriter(System.out);
         new HelpFormatter().printHelp(
                 writer,
-                180,
+                HELP_OUTPUT_LINE_WIDTH,
                 this.getClass().getSimpleName(),
                 message,
                 options,
@@ -109,6 +161,11 @@ protected void printHelpAndExit(final Options options, int status, String messag
         System.exit(status);
     }
 
+    /**
+     * Configures command-line options for the ChronicleHistoryReaderMain.
+     *
+     * @return Configured {@link Options} object
+     */
     @NotNull
     protected Options options() {
         final Options options = new Options();

src/main/java/net/openhft/chronicle/queue/ChronicleReaderMain.java

@@ -34,14 +34,34 @@
 import static java.util.Arrays.stream;
 
 /**
- * Display records in a Chronicle in a text form.
+ * Main class for reading and displaying records from a Chronicle Queue in text form.
+ * Provides several command-line options to control behavior such as including/excluding records
+ * based on regex, following a live queue, or displaying records in various formats.
  */
 public class ChronicleReaderMain {
 
+    private static final int HELP_OUTPUT_LINE_WIDTH = 180;
+
+    /**
+     * Entry point of the application. Initializes the {@link ChronicleReaderMain} instance and
+     * passes command-line arguments for execution.
+     *
+     * @param args Command-line arguments
+     */
     public static void main(@NotNull String[] args) {
         new ChronicleReaderMain().run(args);
     }
 
+    /**
+     * Adds an option to the provided {@link Options} object for command-line parsing.
+     *
+     * @param options     The options object to add the option to
+     * @param opt         The short name of the option
+     * @param argName     The name of the argument
+     * @param hasArg      Whether the option takes an argument
+     * @param description Description of the option
+     * @param isRequired  Whether the option is required
+     */
     public static void addOption(final Options options,
                                  final String opt,
                                  final String argName,
@@ -54,6 +74,12 @@ public static void addOption(final Options options,
         options.addOption(option);
     }
 
+    /**
+     * Runs the Chronicle Reader with the provided command-line arguments.
+     * Configures the {@link ChronicleReader} and executes the reader.
+     *
+     * @param args Command-line arguments
+     */
     protected void run(@NotNull String[] args) {
         final Options options = options();
         final CommandLine commandLine = parseCommandLine(args, options);
@@ -65,35 +91,63 @@ protected void run(@NotNull String[] args) {
         chronicleReader.execute();
     }
 
+    /**
+     * Creates and returns a new instance of {@link ChronicleReader}.
+     *
+     * @return A new instance of {@link ChronicleReader}
+     */
     protected ChronicleReader chronicleReader() {
         return new ChronicleReader();
     }
 
+    /**
+     * Parses the command-line arguments using Apache Commons CLI.
+     * If the help option is provided, prints the help message and exits.
+     *
+     * @param args    Command-line arguments
+     * @param options Command-line options available
+     * @return The parsed {@link CommandLine} object
+     */
     protected CommandLine parseCommandLine(final @NotNull String[] args, final Options options) {
         final CommandLineParser parser = new DefaultParser();
         CommandLine commandLine = null;
         try {
             commandLine = parser.parse(options, args);
 
+            // Print help if 'h' option is provided
             if (commandLine.hasOption('h')) {
                 printHelpAndExit(options, 0);
             }
         } catch (ParseException e) {
+            // On parsing error, print help with an error message
             printHelpAndExit(options, 1, e.getMessage());
         }
 
         return commandLine;
     }
 
+    /**
+     * Prints help information and exits the application.
+     *
+     * @param options Command-line options
+     * @param status  Exit status code
+     */
     protected void printHelpAndExit(final Options options, int status) {
         printHelpAndExit(options, status, null);
     }
 
+    /**
+     * Prints help information along with an optional message and exits the application.
+     *
+     * @param options Command-line options
+     * @param status  Exit status code
+     * @param message Optional message to display before help
+     */
     protected void printHelpAndExit(final Options options, int status, String message) {
         final PrintWriter writer = new PrintWriter(System.out);
         new HelpFormatter().printHelp(
                 writer,
-                180,
+                HELP_OUTPUT_LINE_WIDTH,
                 this.getClass().getSimpleName(),
                 message,
                 options,
@@ -106,14 +160,23 @@ protected void printHelpAndExit(final Options options, int status, String messag
         System.exit(status);
     }
 
+    /**
+     * Configures the {@link ChronicleReader} based on the command-line options.
+     * Supports various options like regex filtering, tailing the queue, and more.
+     *
+     * @param chronicleReader The ChronicleReader instance to configure
+     * @param commandLine     Parsed command-line options
+     */
     protected void configureReader(final ChronicleReader chronicleReader, final CommandLine commandLine) {
+        // Set up message sink; squash output to single line if 'l' option is provided
         final Consumer<String> messageSink = commandLine.hasOption('l') ?
                 s -> System.out.println(s.replaceAll("\n", "")) :
                 System.out::println;
-        chronicleReader.
-                withMessageSink(messageSink).
-                withBasePath(Paths.get(commandLine.getOptionValue('d')));
+        chronicleReader
+                .withMessageSink(messageSink) // Configure the message sink
+                .withBasePath(Paths.get(commandLine.getOptionValue('d'))); // Set base path for chronicle queue files
 
+        // Apply various optional configurations based on command-line options
         if (commandLine.hasOption('i')) {
             stream(commandLine.getOptionValues('i')).forEach(chronicleReader::withInclusionRegex);
         }
@@ -178,6 +241,11 @@ protected void configureReader(final ChronicleReader chronicleReader, final Comm
         }
     }
 
+    /**
+     * Configures the available command-line options for the {@link ChronicleReaderMain}.
+     *
+     * @return A configured {@link Options} object with all available options
+     */
     @NotNull
     protected Options options() {
         final Options options = new Options();

src/main/java/net/openhft/chronicle/queue/ChronicleWriterMain.java

@@ -20,8 +20,19 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * The entry point for writing records to a Chronicle Queue.
+ * This class delegates the writing task to the internal {@link net.openhft.chronicle.queue.internal.writer.ChronicleWriterMain}.
+ */
 public class ChronicleWriterMain {
 
+    /**
+     * Main method for executing the ChronicleWriterMain.
+     * It delegates to the internal writer implementation to run the application with the given arguments.
+     *
+     * @param args Command-line arguments for the writer
+     * @throws Exception if an error occurs during execution
+     */
     public static void main(@NotNull String[] args) throws Exception {
         new net.openhft.chronicle.queue.internal.writer.ChronicleWriterMain().run(args);
     }

src/main/java/net/openhft/chronicle/queue/CycleCalculator.java

@@ -20,7 +20,23 @@
 
 import net.openhft.chronicle.core.time.TimeProvider;
 
+/**
+ * Functional interface representing a calculator for determining the current cycle based on
+ * a {@link RollCycle}, a {@link TimeProvider}, and an optional offset in milliseconds.
+ * <p>
+ * This interface is intended to be used for customizing the cycle calculation logic in
+ * Chronicle Queue, particularly when working with different roll cycles or time-based patterns.
+ */
 @FunctionalInterface
 public interface CycleCalculator {
+
+    /**
+     * Calculates the current cycle based on the provided {@link RollCycle}, {@link TimeProvider}, and an offset in milliseconds.
+     *
+     * @param rollCycle     The roll cycle that defines the periodicity of the data rolls
+     * @param timeProvider  The time provider that supplies the current time
+     * @param offsetMillis  The time offset in milliseconds, typically used for adjusting the cycle calculation
+     * @return The current cycle as an integer, calculated according to the given roll cycle and time
+     */
     int currentCycle(final RollCycle rollCycle, final TimeProvider timeProvider, final long offsetMillis);
 }

src/main/java/net/openhft/chronicle/queue/DefaultCycleCalculator.java

@@ -20,9 +20,27 @@
 
 import net.openhft.chronicle.core.time.TimeProvider;
 
+/**
+ * Singleton enum implementation of {@link CycleCalculator} that provides a default mechanism
+ * for calculating the current cycle based on the provided {@link RollCycle} and {@link TimeProvider}.
+ * <p>
+ * This enum ensures there is only one instance of the cycle calculator, represented by {@code INSTANCE}.
+ */
 public enum DefaultCycleCalculator implements CycleCalculator {
+    /**
+     * The single instance of the {@code DefaultCycleCalculator}.
+     */
     INSTANCE;
 
+    /**
+     * Calculates the current cycle by delegating to the provided {@link RollCycle}.
+     * Uses the {@link TimeProvider} and an optional offset in milliseconds to determine the current cycle.
+     *
+     * @param rollCycle     The roll cycle that defines the periodicity of the data rolls
+     * @param timeProvider  The time provider that supplies the current time
+     * @param offsetMillis  The time offset in milliseconds, typically used for adjusting the cycle calculation
+     * @return The current cycle as an integer, calculated according to the given roll cycle and time
+     */
     @Override
     public int currentCycle(final RollCycle rollCycle, final TimeProvider timeProvider, final long offsetMillis) {
         return rollCycle.current(timeProvider, offsetMillis);