Add detailed Javadoc comments to core classes

Extensive Javadoc comments were added to many classes and methods in the AICC, SCORM, CMI5, LOM, and file access implementations to improve code documentation and clarity. Three utility/test scripts (TestJsonSerialization.java, fix_classes.sh, remove_builder_annotations.sh) were removed as part of codebase cleanup.

Author: jcputney

TestJsonSerialization.java

@@ -100,8 +100,8 @@ public abstract class AbstractS3FileAccess implements FileAccess {
    * A thread-safe cache storing the list of all file paths within the module.
    * <p>
    * This cache is intended to improve performance for file-related operations by storing the result
-   * of a full scan of the S3 bucket or prefix. The cache is stored in an {@link AtomicReference}
-   * to ensure safe publication across threads once populated.
+   * of a full scan of the S3 bucket or prefix. The cache is stored in an {@link AtomicReference} to
+   * ensure safe publication across threads once populated.
    * <p>
    * Modifications to this cache should be controlled to maintain data consistency across the class,
    * particularly when the underlying S3 bucket contents change.
@@ -445,6 +445,12 @@ public String fullPath(String relativePath) {
     return rootPath + "/" + path;
   }
 
+  /**
+   * Retrieves the root path of the current instance.
+   *
+   * @return the root path as a String
+   */
+  @Override
   public String getRootPath() {
     return this.rootPath;
   }
@@ -507,6 +513,13 @@ protected InputStream getFileContentsBase(String path) throws IOException {
     }
   }
 
+  /**
+   * Wraps the provided input stream with additional processing or functionality.
+   *
+   * @param stream the original input stream to be wrapped
+   * @param fileSize the size of the file associated with the input stream, in bytes
+   * @return an InputStream instance which provides a wrapped version of the original input stream
+   */
   protected abstract InputStream getInputStreamWrapper(InputStream stream, long fileSize);
 
   /**

fix_classes.sh

@@ -132,6 +132,12 @@ public long getTotalSize() throws IOException {
     return -1;
   }
 
+  /**
+   * Retrieves the root path used for file access.
+   *
+   * @return The root path as a string.
+   */
+  @Override
   public String getRootPath() {
     return this.rootPath;
   }

remove_builder_annotations.sh

@@ -42,6 +42,20 @@ public class DefaultModuleFileProvider implements ModuleFileProvider {
    * The name of the xAPI send statement file.
    */
   public static final String XAPI_SEND_STATEMENT_FILE = "sendStatement.js";
+
+  /**
+   * A FileAccess instance used to handle file operations within the module package.
+   * <p>
+   * This variable provides an abstraction layer for file-related operations, such as reading,
+   * checking existence, and accessing files in a consistent manner. It is integral to the
+   * functionality provided by the DefaultModuleFileProvider.
+   * <p>
+   * The FileAccess instance ensures that file operations are centralized and can be delegated
+   * appropriately, facilitating modular and testable design.
+   * <p>
+   * This field is immutable and must be initialized during the construction of the
+   * DefaultModuleFileProvider.
+   */
   private final FileAccess fileAccess;
 
   /**

src/main/java/dev/jcputney/elearning/parser/impl/AbstractS3FileAccess.java

@@ -51,9 +51,40 @@
  */
 public class InMemoryFileAccess implements FileAccess, AutoCloseable {
 
+  /**
+   * Represents the root path of the detected directory structure within the ZIP data.
+   * <p>
+   * The root path is determined by analyzing the file entries from the input ZIP data. If all files
+   * are contained within a single top-level directory, the root path will be set to that
+   * directory's name. If the files are distributed across multiple directories or at the root of
+   * the ZIP, the root path will be an empty string.
+   * <p>
+   * This variable is final and is initialized during the loading process of the in-memory file
+   * system.
+   */
   private final String rootPath;
+
+  /**
+   * A list of file entries representing the in-memory files loaded from a ZIP file. Each entry
+   * corresponds to a file within the in-memory file system, encapsulating its path, content, and
+   * size.
+   */
   private final List<FileEntry> fileEntries;
+
+  /**
+   * A set containing the unique directory paths detected in the in-memory file system.
+   * <p>
+   * This set ensures that no duplicate directory paths are stored and is used internally for
+   * operations that require knowledge of the directory structure, such as detecting parent
+   * directories or listing directory contents.
+   */
   private final Set<String> directories;
+
+  /**
+   * Represents the total size of all files stored in the in-memory file system. This value is
+   * calculated during the loading of ZIP data and reflects the combined size of all files,
+   * excluding additional metadata or directory structures.
+   */
   private final long totalSize;
 
   /**
@@ -102,6 +133,13 @@ public InMemoryFileAccess(InputStream zipInputStream) throws IOException {
     this.rootPath = detectRootPath();
   }
 
+  /**
+   * Retrieves the root path for the in-memory file system. The root path is typically determined
+   * during the initialization of the instance and provides the base directory for all file
+   * operations within the system.
+   *
+   * @return The root path as a string.
+   */
   @Override
   public String getRootPath() {
     return rootPath;
@@ -206,6 +244,12 @@ public List<String> getAllFiles() throws IOException {
         .toList();
   }
 
+  /**
+   * Retrieves the total size of all files stored in the in-memory file system.
+   *
+   * @return The total size of all files in bytes.
+   * @throws IOException If an error occurs while calculating the total size.
+   */
   @Override
   public long getTotalSize() throws IOException {
     return totalSize;
@@ -384,8 +428,22 @@ private String getSimilarFiles(String targetPath) {
    */
   private static class FileEntry {
 
+    /**
+     * The file path associated with this file entry, representing the location or identifier of the
+     * file within an in-memory file system.
+     */
     private final String path;
+
+    /**
+     * Holds the content of the file represented by this file entry. This is a byte array that
+     * stores the raw data of the file in memory.
+     */
     private final byte[] content;
+
+    /**
+     * Represents the size of the file in bytes. This value is derived from the length of the
+     * content array and indicates the total amount of data stored in this file entry.
+     */
     private final long size;
 
     FileEntry(String path, byte[] content) {
@@ -394,14 +452,29 @@ private static class FileEntry {
       this.size = content.length;
     }
 
+    /**
+     * Retrieves the file path associated with this file entry.
+     *
+     * @return the file path as a string
+     */
     String getPath() {
       return path;
     }
 
+    /**
+     * Retrieves the content of the file represented by this file entry.
+     *
+     * @return a byte array containing the raw data of the file
+     */
     byte[] getContent() {
       return content;
     }
 
+    /**
+     * Retrieves the size of the file in bytes.
+     *
+     * @return the file size as a long value
+     */
     long getSize() {
       return size;
     }

src/main/java/dev/jcputney/elearning/parser/impl/ClasspathFileAccess.java

@@ -201,6 +201,12 @@ public long getTotalSize() throws IOException {
     }
   }
 
+  /**
+   * Retrieves the root path for file access.
+   *
+   * @return The root path as a String.
+   */
+  @Override
   public String getRootPath() {
     return this.rootPath;
   }