Add javadocs

Author: lfir

src/main/java/cf/maybelambda/fedora/ConfigManager.java

@@ -30,6 +30,23 @@ public class ConfigManager {
 
     private static final List<String> adminGroups = List.of("docker", "libvirt", "vboxsf", "vboxusers");
 
+    /**
+     * Reads all lines of a resource / configuration file.
+     *
+     * <p>The method first attempts to locate the file on the real filesystem under
+     * {@code CONFIG_DIR}/{@code filename}. If that file exists, its contents are read.
+     * When the file is not found in the configured directory, the method falls back
+     * to loading it from the class‑path (e.g. {@code /filename}).
+     *
+     * <p>The resulting list contains each line of the resource exactly as it appears,
+     * without any trailing line‑separator characters.
+     *
+     * @param filename The name of the file to read
+     * @return List of lines from the requested resource
+     * @throws IOException If an I/O error occurs while reading the file, 
+     *                     or if the resource cannot be located on either the filesystem
+     *                     nor the class‑path
+     */
     static List<String> readResourceLines(String filename) throws IOException {
         Path path = Path.of(CONFIG_DIR, filename);
         if (Files.exists(path)) {
@@ -41,6 +58,19 @@ static List<String> readResourceLines(String filename) throws IOException {
         }
     }
 
+    /**
+     * Loads package names from a configuration file.
+     *
+     * <p>Reads the resource identified by {@code filename} located under 
+     * {@link #CONFIG_DIR CONFIG_DIR} or the class-path. 
+     * Each non‑empty line that does not start with '#' is treated as a package name.
+     * Lines beginning with '#' are considered comments and ignored. If the file cannot be
+     * accessed, an error message is written to {@code System.err} and an empty list is returned.
+     *
+     * @param filename The resource file name (e.g., {@code dnf-install.cf})
+     * @return List containing the package identifiers found in the
+     *         file; may be empty if no valid entries are present or an I/O error occurs
+     */
     static List<String> loadPackageNamesFrom(String filename) {
         List<String> packages = new ArrayList<>();
         try {

src/main/java/cf/maybelambda/fedora/ConsoleIOHelper.java

@@ -17,12 +17,33 @@ public class ConsoleIOHelper {
     private static final String EXCLUDE_PROMPT = "Type in the number and/or range of numbers of packages to exclude "
         + "(comma-separated, i.e. 2,3,5..9)\nor press Enter to keep all: ";
 
+    /**
+     * Prompts the user for a yes/no confirmation based on the provided {@code prompt}.
+     *
+     * @param scanner {@link Scanner} used to read user input; must not be {@code null}
+     * @param prompt The message displayed before the confirmation prompt
+     * @return {@code true} if the user confirms with "y" or "yes" (case insensitive),
+     *         {@code false} otherwise
+     */
     static boolean confirm(Scanner scanner, String prompt) {
         System.out.print(prompt + " [y/N]: ");
         String input = scanner.nextLine().trim().toLowerCase();
         return input.equals("y") || input.equals("yes");
     }
 
+    /**
+     * Prompts the user to specify which packages should be excluded from further processing.
+     *
+     * <p>The method prints an enumerated list of available package names and then reads a line
+     * containing comma‑separated indices, ranges (e.g., "2..4"), or both. It validates that the
+     * input is empty or contains number/s and/or range/s.
+     * A list containing only the non‑excluded items is returned.
+     *
+     * @param packages A list of package identifiers presented for selection; must not be {@code null}
+     * @param scanner {@link Scanner} used to read user input; must not be {@code null}
+     * @return List of packages that were not selected for exclusion
+     * @throws RuntimeException If the user input does not conform to the expected format
+     */
     static List<String> promptForExclusions(List<String> packages, Scanner scanner) {
         for (int i = 0; i < packages.size(); i++) {
             System.out.printf("%2d. %s\n", i + 1, packages.get(i));
@@ -66,6 +87,13 @@ static List<String> promptForExclusions(List<String> packages, Scanner scanner)
         return filtered;
     }
 
+    /**
+     * Prints help documentation to standard output.
+     *
+     * <p>Retrieves help info from {@link ConfigManager#getHelpText()} and outputs it.
+     * If an {@link IOException} occurs while reading the help file,
+     * an error message is written to standard error.
+     */
     static void printHelp() {
         try {
             List<String> lines = ConfigManager.getHelpText();
@@ -75,10 +103,34 @@ static void printHelp() {
         }
     }
 
+    /**
+     * Wraps a string in ANSI color codes when the underlying terminal supports it.
+     *
+     * <p>If ANSI escape sequences are supported for the given {@code term} and an active console is present,
+     * the resulting string will be prefixed with {@code ansiColorCode} and suffixed with a reset code.
+     * If coloring is not supported, the original string is returned unchanged.
+     *
+     * @param str The text to be colored; must not be {@code null}
+     * @param ansiColorCode One of the predefined ANSI color codes (e.g., {@link #YELLOW});
+     *                      may also be an empty string for no coloring
+     * @return A possibly-colored version of {@code str}, or {@code str} itself if ANSI is unsupported
+     */
     static String color(String str, String ansiColorCode) {
         return isANSISupported(System.getenv("TERM"), System.console()) ? ansiColorCode + str + RESET : str;
     }
 
+    /**
+     * Determines whether the current environment likely supports ANSI escape sequences.
+     *
+     * <p>Checks that the terminal type ({@code term}) is non‑null and not equal to "dumb",
+     * and verifies that an active console stream exists. Returns {@code true} when these
+     * conditions indicate that colored output can be rendered; otherwise returns {@code false}.
+     *
+     * @param term Value of the TERM environment variable
+     * @param console Underlying console object from {@link Console}; may be {@code null}
+     *                on some platforms
+     * @return {@code true} if ANSI escape sequences are supported, {@code false} otherwise
+     */
     static boolean isANSISupported(String term, Console console) {
         return console != null && term != null && !term.isEmpty() && !"dumb".equals(term);
     }

src/main/java/cf/maybelambda/fedora/Main.java

@@ -24,10 +24,23 @@ public class Main {
     static List<String> CMD_ADD_USER_TO_GROUP = asList("sudo", "usermod", "-aG");
     static List<String> CMD_SYSTEMCTL_ENABLE = asList("sudo", "systemctl", "enable", "--now", "cockpit.socket"); // single arg appended to cmd
 
+    /**
+     * Entry point of the program.
+     * Delegates execution to the {@code Main.run} method.
+     */
     public static void main(String[] args) {
         run(args, new PostInstallUpdater());
     }
 
+    /**
+     * Executes the setup workflow based on provided command-line arguments.
+     *
+     * <p>This method parses command-line arguments and checks for known flags, sets up interactive prompts,
+     * and orchestrates various system configuration steps.
+     *
+     * @param args Command-line arguments passed to the program at startup
+     * @param updater {@link PostInstallUpdater} responsible for executing OS commands
+     */
     static void run(String[] args, PostInstallUpdater updater) {
         if (asList(args).contains("-h") || asList(args).contains("--help")) {
             ConsoleIOHelper.printHelp();

src/main/java/cf/maybelambda/fedora/PostInstallUpdater.java

@@ -22,10 +22,29 @@ void setDryRun(boolean dryRun) {
         this.dryRun = dryRun;
     }
 
+    /**
+     * Creates a {@link ProcessBuilder} configured with the given command array.
+     * 
+     * @param cmd An array containing the executable command parts
+     * @return New {@code ProcessBuilder} instance initialized with {@code cmd}
+     *
+     */
     ProcessBuilder createProcessBuilder(String[] cmd) {
         return new ProcessBuilder(cmd);
     }
 
+    /**  
+     * Executes a shell command built from {@code baseCmd} followed by {@code args}.  
+     * 
+     * <p>Prints the full command, displays each line of output,
+     * waits for termination, reports the exit status, and returns that status code.
+     * In dry‑run mode, it only informs the caller that no execution will occur.
+     *
+     * @param baseCmd List containing the initial command tokens  
+     * @param args Additional arguments to append to {@code baseCmd}  
+     * @return Exit code of the executed process, or {@code -1} if execution was not performed
+     *         due to an error, or {@code 0} if dry-run was enabled
+     */
     int runCommand(List<String> baseCmd, List<String> args) {
         String[] command = concat(baseCmd.stream(), args.stream()).toArray(String[]::new);
         System.out.println("Executing shell command: " + color(String.join(" ", command), BLUE));