add package-info.java files for all CLI packages with detailed documentation

Author: Splatcrafter

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/AetherCli.java

@@ -76,9 +76,28 @@
 public class AetherCli implements Callable<Integer> {
 
     /**
-     * Main entry point for the CLI.
+     * Main entry point for the Aether Datafixers CLI application.
      *
-     * @param args command-line arguments
+     * <p>This method initializes the picocli {@link CommandLine} parser with the
+     * root {@link AetherCli} command and executes it with the provided arguments.
+     * The process exit code is set based on the command execution result.</p>
+     *
+     * <h3>Exit Codes</h3>
+     * <ul>
+     *   <li>{@code 0} - Success (or help displayed)</li>
+     *   <li>{@code 1} - Error occurred during command execution</li>
+     *   <li>{@code 2} - Validation found files needing migration (validate command only)</li>
+     * </ul>
+     *
+     * <h3>Configuration</h3>
+     * <p>The CommandLine instance is configured with:</p>
+     * <ul>
+     *   <li>Case-insensitive enum value parsing enabled</li>
+     * </ul>
+     *
+     * @param args command-line arguments passed from the shell; may be empty
+     *             but should not be {@code null}
+     * @see CommandLine#execute(String...)
      */
     public static void main(final String[] args) {
         final int exitCode = new CommandLine(new AetherCli())
@@ -87,6 +106,20 @@ public static void main(final String[] args) {
         System.exit(exitCode);
     }
 
+    /**
+     * Executes the root command when invoked without a subcommand.
+     *
+     * <p>When the CLI is invoked without specifying a subcommand (e.g., just
+     * {@code aether-cli}), this method is called. It displays the help message
+     * showing available commands and options.</p>
+     *
+     * <p>This behavior provides a user-friendly experience where running the
+     * CLI without arguments shows how to use it, rather than doing nothing
+     * or showing an error.</p>
+     *
+     * @return {@code 0} indicating successful execution (help was displayed)
+     * @see CommandLine#usage(Object, java.io.PrintStream)
+     */
     @Override
     public Integer call() {
         // Print help when no subcommand is specified

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/bootstrap/BootstrapLoader.java

@@ -22,45 +22,95 @@
 
 package de.splatgames.aether.datafixers.cli.bootstrap;
 
+import com.google.common.base.Preconditions;
 import de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap;
 import org.jetbrains.annotations.NotNull;
 
 import java.lang.reflect.Constructor;
 import java.util.ServiceLoader;
 
 /**
- * Loads {@link DataFixerBootstrap} implementations.
+ * Utility class for loading {@link DataFixerBootstrap} implementations at runtime.
+ *
+ * <p>This class provides multiple methods for discovering and instantiating
+ * bootstrap implementations:</p>
  *
  * <h2>Discovery Methods</h2>
  * <ol>
- *   <li>Explicit class name via {@code --bootstrap} option</li>
- *   <li>ServiceLoader discovery via {@code META-INF/services}</li>
+ *   <li><b>Explicit class name</b> via {@link #load(String)} - Used when the CLI
+ *       receives the {@code --bootstrap} option with a fully qualified class name</li>
+ *   <li><b>ServiceLoader discovery</b> via {@link #discover()} or {@link #loadFirst()} -
+ *       Automatically discovers implementations registered in
+ *       {@code META-INF/services/de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap}</li>
  * </ol>
  *
+ * <h2>Thread Safety</h2>
+ * <p>All methods are thread-safe as they do not maintain any mutable state.</p>
+ *
+ * <h2>Example Usage</h2>
+ * <pre>{@code
+ * // Load by explicit class name
+ * DataFixerBootstrap bootstrap = BootstrapLoader.load("com.example.MyBootstrap");
+ *
+ * // Auto-discover via ServiceLoader
+ * DataFixerBootstrap bootstrap = BootstrapLoader.loadFirst();
+ *
+ * // Iterate over all discovered bootstraps
+ * for (DataFixerBootstrap bootstrap : BootstrapLoader.discover()) {
+ *     System.out.println("Found: " + bootstrap.getClass().getName());
+ * }
+ * }</pre>
+ *
  * @author Erik Pfoertner
+ * @see DataFixerBootstrap
+ * @see BootstrapLoadException
+ * @see java.util.ServiceLoader
  * @since 0.3.0
  */
 public final class BootstrapLoader {
 
+    /**
+     * Private constructor to prevent instantiation.
+     *
+     * <p>This is a utility class with only static methods and should not be instantiated.</p>
+     */
     private BootstrapLoader() {
         // Utility class
     }
 
     /**
-     * Loads a bootstrap by its fully qualified class name.
+     * Loads a bootstrap implementation by its fully qualified class name.
      *
-     * <p>The class must:</p>
+     * <p>This method uses reflection to load and instantiate the specified class.
+     * The class must satisfy the following requirements:</p>
      * <ul>
-     *   <li>Implement {@link DataFixerBootstrap}</li>
-     *   <li>Have a public no-argument constructor</li>
+     *   <li>Must implement {@link DataFixerBootstrap}</li>
+     *   <li>Must have a public no-argument constructor</li>
+     *   <li>Must be accessible on the current thread's context class loader</li>
      * </ul>
      *
-     * @param className the fully qualified class name
-     * @return the bootstrap instance
-     * @throws BootstrapLoadException if loading fails
+     * <h3>Error Handling</h3>
+     * <p>All reflection-related exceptions are wrapped in {@link BootstrapLoadException}
+     * with descriptive error messages to aid debugging:</p>
+     * <ul>
+     *   <li>{@code ClassNotFoundException} - Class not found on classpath</li>
+     *   <li>{@code NoSuchMethodException} - Missing public no-arg constructor</li>
+     *   <li>{@code ReflectiveOperationException} - Instantiation failure</li>
+     * </ul>
+     *
+     * @param className the fully qualified class name (e.g., "com.example.MyBootstrap"),
+     *                  must not be {@code null}
+     * @return the instantiated bootstrap instance, never {@code null}
+     * @throws BootstrapLoadException if the class cannot be found, does not implement
+     *                                DataFixerBootstrap, lacks a no-arg constructor,
+     *                                or instantiation fails
+     * @see #discover()
+     * @see #loadFirst()
      */
     @NotNull
     public static DataFixerBootstrap load(@NotNull final String className) {
+        Preconditions.checkNotNull(className, "className must not be null");
+
         try {
             final Class<?> clazz = Class.forName(className);
 
@@ -87,20 +137,52 @@ public static DataFixerBootstrap load(@NotNull final String className) {
     }
 
     /**
-     * Discovers bootstraps via ServiceLoader.
+     * Discovers all bootstrap implementations via Java's {@link ServiceLoader} mechanism.
+     *
+     * <p>This method searches for implementations registered in:</p>
+     * <pre>
+     * META-INF/services/de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap
+     * </pre>
      *
-     * @return iterable of discovered bootstraps
+     * <p>The returned iterable is lazy - implementations are instantiated on demand
+     * as the iterator is consumed. Each call to this method creates a fresh
+     * ServiceLoader instance.</p>
+     *
+     * <h3>Registration</h3>
+     * <p>To register a bootstrap for discovery, create a file at:</p>
+     * <pre>
+     * src/main/resources/META-INF/services/de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap
+     * </pre>
+     * <p>containing the fully qualified class name of your implementation.</p>
+     *
+     * @return an iterable over all discovered bootstrap implementations;
+     *         may be empty if none are registered
+     * @see ServiceLoader#load(Class)
+     * @see #loadFirst()
+     * @see #load(String)
      */
     @NotNull
     public static Iterable<DataFixerBootstrap> discover() {
         return ServiceLoader.load(DataFixerBootstrap.class);
     }
 
     /**
-     * Loads the first available bootstrap from ServiceLoader.
+     * Loads the first available bootstrap from the ServiceLoader.
+     *
+     * <p>This is a convenience method that returns the first bootstrap found
+     * via {@link #discover()}. Useful when only one bootstrap is expected to
+     * be registered in the application.</p>
+     *
+     * <p>The order in which bootstraps are discovered is not guaranteed and
+     * depends on the classpath order. If multiple bootstraps are registered,
+     * consider using {@link #discover()} to iterate over all of them or
+     * {@link #load(String)} to specify an exact implementation.</p>
      *
-     * @return the first bootstrap found
-     * @throws BootstrapLoadException if no bootstrap is found
+     * @return the first discovered bootstrap implementation, never {@code null}
+     * @throws BootstrapLoadException if no bootstrap implementations are found
+     *                                via ServiceLoader
+     * @see #discover()
+     * @see #load(String)
      */
     @NotNull
     public static DataFixerBootstrap loadFirst() {

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/bootstrap/package-info.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 Splatgames.de Software and Contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Bootstrap loading utilities for the CLI.
+ *
+ * <p>This package provides utilities for loading
+ * {@link de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap}
+ * implementations at runtime via class name or ServiceLoader discovery.</p>
+ *
+ * <h2>Key Classes</h2>
+ * <ul>
+ *   <li>{@link de.splatgames.aether.datafixers.cli.bootstrap.BootstrapLoader}
+ *       - Loads bootstraps by class name or via ServiceLoader</li>
+ *   <li>{@link de.splatgames.aether.datafixers.cli.bootstrap.BootstrapLoadException}
+ *       - Exception thrown when bootstrap loading fails</li>
+ * </ul>
+ *
+ * <h2>Usage</h2>
+ * <pre>{@code
+ * // Load by fully qualified class name
+ * DataFixerBootstrap bootstrap = BootstrapLoader.load("com.example.MyBootstrap");
+ *
+ * // Discover via ServiceLoader
+ * DataFixerBootstrap bootstrap = BootstrapLoader.loadFirst();
+ * }</pre>
+ *
+ * @see de.splatgames.aether.datafixers.cli.bootstrap.BootstrapLoader
+ * @see de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap
+ * @since 0.3.0
+ */
+package de.splatgames.aether.datafixers.cli.bootstrap;