Extend/Update API part 11 (#61)

Author: JavaSaBr

.github/copilot-instructions.md

@@ -51,6 +51,39 @@ Common pitfalls and fixes
 Linting & style
 - The root does not expose an obvious global formatting tool (no Spotless or root Checkstyle detected). Use the existing code style. Run `./gradlew check` to execute configured verification tasks.
 
+Testing conventions
+- Use AssertJ for assertions (import `org.assertj.core.api.Assertions`), not JUnit's `Assertions`.
+- Test class naming: `<ClassName>Test.java` in the same package under `src/test/java`.
+- Test class visibility: use package-private (no `public` modifier) for test classes.
+- Test method naming: `should<ExpectedBehavior>` pattern (e.g., `shouldReturnEmptyArrayForNullInput`).
+- Use given/when/then comments with trailing colons to structure test methods (e.g., `// given:`, `// when:`, `// then:`, `// when/then:`).
+- For cleanup steps, use `// cleanup:` comment section at the end of the test method.
+- Prefer project collections (e.g., `MutableArray`) over JDK collections (e.g., `ArrayList`) in tests when appropriate.
+- Use proper imports instead of fully qualified class names in test code.
+- When adding new public methods, ensure corresponding unit tests are added.
+- Use JUnit's `@TempDir Path tempDir` parameter injection for tests that need temporary directories instead of manually creating temp directories with `Files.createTempDirectory()`.
+- For resources created outside `@TempDir` (e.g., `Files.createTempFile()`), add explicit cleanup in the `// cleanup:` section.
+- For `assertThat()` calls: break method chains onto new lines with indentation when the assertion has arguments or multiple chained methods (e.g., `assertThat(result)\n    .isEqualTo("expected")`). Short simple assertions can stay on one line.
+- For fluent builder/method chains: break onto new lines with indentation (e.g., `tempDir\n    .resolve("level1")\n    .resolve("level2")`).
+
+Javadoc conventions
+- All public classes, interfaces, and methods should have javadoc.
+- Javadoc must include `@since` tag with version (e.g., `@since 10.0.0`).
+- Use short, active-voice descriptions (e.g., "Returns an array" not "Return an array").
+- Do not use trailing periods in `@param` and `@return` descriptions (e.g., `@param value the value` not `@param value the value.`).
+- Include `@param` and `@return` tags for non-trivial methods.
+- Omit javadoc for simple getters/setters (e.g., `getArch()`, `setArch(String)`); they are self-explanatory.
+- Omit obvious field comments that just repeat the field name (e.g., `/** The name. */ private String name;`).
+- Omit obvious constant comments (e.g., `/** The constant FOO. */ public static final String FOO = "foo";`).
+- Type parameter descriptions should use consistent format: "the type of..." (e.g., `@param <T> the type of elements` not `@param <T> the element type`).
+- Do not generate javadoc for implementation classes (only interfaces and public API classes).
+- For `@see` tags, avoid duplicate references (e.g., use `@see Math#sin(double)` not `@see Math#sin(double) Math#sin(double)`).
+- For functional interfaces:
+    - Consumer descriptions must include "and returns no result" (e.g., "Represents an operation that accepts an int and an object argument, and returns no result.").
+    - Use type-specific @param descriptions (e.g., "the int argument", "the object argument") instead of generic "the first argument".
+    - Function @return should use "the function result" for consistency.
+    - Predicate @return should use "true if the arguments match the predicate".
+
 Project layout & where to change things
 - Root-level important files:
     - `build.gradle` — root build settings, wrapper config.

.github/skills/generate-javadoc.md

@@ -8,6 +8,8 @@ When the user asks to:
 - Generate javadocs for a module
 - Add documentation to public APIs
 - Document interfaces/classes with `@since` tags
+- Review and fix existing javadocs
+- Clean up javadoc formatting
 
 ## Requirements
 
@@ -16,23 +18,42 @@ When the user asks to:
 2. **Skip implementation classes** - files in `impl/` packages are NOT documented
 3. **Skip test classes** - files in `src/test/` are NOT documented
 
+### What to Omit
+1. **Simple getters/setters** - methods like `getArch()`, `setArch(String)` are self-explanatory
+2. **Obvious field comments** - avoid comments that just repeat the field name (e.g., `/** The name. */ private String name;`)
+3. **Obvious constructor javadocs** - avoid comments like "Instantiates a new Foo"
+4. **Obvious constant comments** - avoid comments like "The constant FOO" for `public static final String FOO`
+
+### Formatting Rules
+1. **Active voice** - use "Returns" not "Return", "Creates" not "Create"
+2. **No trailing periods** - in `@param` and `@return` descriptions (e.g., `@param value the value` not `@param value the value.`)
+3. **No duplicate @see references** - use `@see Math#sin(double)` not `@see Math#sin(double) Math#sin(double)`
+4. **Lowercase @param/@return descriptions** - start with lowercase (e.g., `@param value the value` not `@param value The value`)
+5. **Consistent type parameter format** - use "the type of..." pattern (e.g., `@param <T> the type of elements` not `@param <T> the element type`)
+6. **Descriptive @param names** - for functional interfaces, use type-specific descriptions (e.g., "the int argument", "the object argument") instead of generic "the first argument"
+
+### Functional Interface Conventions
+1. **Consumer descriptions** - always include "and returns no result" (e.g., "Represents an operation that accepts an int and an object argument, and returns no result.")
+2. **Function @return** - use "the function result" for consistency
+3. **Predicate @return** - use "true if the arguments match the predicate" or "true if the arguments match the predicate, false otherwise"
+4. **Supplier @return** - describe what is supplied (e.g., "the char value" not just "a result")
+
 ### Javadoc Standards
 Each documented element must include:
 
 1. **Class/Interface level:**
-   - Short description of purpose
-   - `@param` for type parameters (if generic)
-   - `@author JavaSaBr`
+   - Short description of purpose (active voice)
+   - `@param` for type parameters with meaningful descriptions (if generic)
    - `@since 10.0.0`
 
 2. **Method level:**
-   - Short description for ALL methods
+   - Short description for non-trivial methods
    - `@param` and `@return` only for **non-trivial** methods
    - `@since 10.0.0`
    - `@throws` only when explicitly thrown
 
 3. **Constants/Fields:**
-   - Short description
+   - Short description (only if not obvious from the name)
    - `@since 10.0.0`
 
 ### Example Format
@@ -42,7 +63,6 @@ Each documented element must include:
  * An immutable array interface that provides type-safe, indexed access to elements.
  *
  * @param <E> the type of elements in this array
- * @author JavaSaBr
  * @since 10.0.0
  */
 public interface Array<E> extends Iterable<E> {
@@ -79,6 +99,37 @@ public interface Array<E> extends Iterable<E> {
 }
 ```
 
+### Functional Interface Example
+
+```java
+/**
+ * Represents an operation that accepts an int and an object argument, and returns no result.
+ *
+ * @param <B> the type of the object argument
+ * @since 10.0.0
+ */
+@FunctionalInterface
+public interface IntObjConsumer<B> {
+
+  /**
+   * Performs this operation on the given arguments.
+   *
+   * @param arg1 the int argument
+   * @param arg2 the object argument
+   * @since 10.0.0
+   */
+  void accept(int arg1, B arg2);
+}
+```
+
+### Common Fixes When Reviewing Existing Javadocs
+- Change "Return the" to "Returns the"
+- Change "Compare the" to "Compares the"
+- Remove trailing periods from `@param` and `@return` lines
+- Remove obvious/redundant javadocs (getters, setters, constants)
+- Remove duplicate `@see` references
+- Add missing `@since` tags
+
 ## Execution Steps
 
 1. **Analyze module structure:**
@@ -94,7 +145,7 @@ public interface Array<E> extends Iterable<E> {
 3. **Read each file** to understand existing documentation state
 
 4. **Add Javadocs** using `replace_string_in_file` tool:
-   - Add class-level Javadoc with description, `@author`, `@since`
+   - Add class-level Javadoc with description and `@since`
    - Add method-level Javadocs with description and `@since`
    - Add `@param`/`@return` only for non-trivial methods
 

README.md

@@ -45,7 +45,7 @@ repositories {
 }
 
 ext {
-    rlibVersion = "10.0.alpha12"
+    rlibVersion = "10.0.alpha13"
 }
 
 dependencies {

build.gradle

@@ -1,4 +1,4 @@
-rootProject.version = "10.0.alpha12"
+rootProject.version = "10.0.alpha13"
 group = 'javasabr.rlib'
 
 allprojects {

rlib-classpath/src/main/java/javasabr/rlib/classpath/ClassPathScanner.java

@@ -10,16 +10,35 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * @author JavaSaBr
+ * Scanner for discovering classes and resources on the classpath.
+ *
+ * @since 10.0.0
  */
 public interface ClassPathScanner {
 
+  /**
+   * The JAR file extension.
+   */
   String JAR_EXTENSION = ".jar";
+
+  /**
+   * The Java source file extension.
+   */
   String SOURCE_EXTENSION = ".java";
+
+  /**
+   * The compiled class file extension.
+   */
   String CLASS_EXTENSION = ".class";
 
+  /**
+   * A null scanner constant.
+   */
   @Nullable ClassPathScanner NULL_SCANNER = null;
 
+  /**
+   * An empty scanner that performs no operations.
+   */
   ClassPathScanner EMPTY_SCANNER = new ClassPathScannerImpl(ClassPathScanner.class.getClassLoader()) {
 
     @Override
@@ -38,55 +57,172 @@ public void addResources(Array<String> resources) {}
     public void scan(Predicate<String> filter) {}
   };
 
+  /**
+   * An empty class loader with no URLs.
+   */
   URLClassLoader EMPTY_CLASS_LOADER = new URLClassLoader(new URL[0], ClassPathScanner.class.getClassLoader());
 
+  /**
+   * A null class loader constant.
+   */
   @Nullable URLClassLoader NULL_CLASS_LOADER = null;
 
+  /**
+   * Adds discovered classes to the specified collection.
+   *
+   * @param classes the collection to add classes to
+   * @since 10.0.0
+   */
   void addClasses(Array<Class<?>> classes);
 
+  /**
+   * Adds discovered resources to the specified collection.
+   *
+   * @param resources the collection to add resources to
+   * @since 10.0.0
+   */
   void addResources(Array<String> resources);
 
+  /**
+   * Sets whether to include the system classpath in scanning.
+   *
+   * @param useSystemClasspath true to include system classpath
+   * @since 10.0.0
+   */
   void useSystemClassPath(boolean useSystemClasspath);
 
+  /**
+   * Finds all implementations of the specified interface.
+   *
+   * @param <T> the type of the interface
+   * @param interfaceClass the interface class to find implementations for
+   * @return an array of implementing classes
+   * @since 10.0.0
+   */
   default <T> Array<Class<T>> findImplementations(Class<T> interfaceClass) {
     MutableArray<Class<T>> result = MutableArray.ofType(Class.class);
     findImplementationsTo(result, interfaceClass);
     return result;
   }
 
+  /**
+   * Finds all implementations of the specified interface and adds them to the container.
+   *
+   * @param <T> the type of the interface
+   * @param container the container to add implementations to
+   * @param interfaceClass the interface class to find implementations for
+   * @since 10.0.0
+   */
   <T> void findImplementationsTo(MutableArray<Class<T>> container, Class<T> interfaceClass);
 
+  /**
+   * Finds all classes that inherit from the specified parent class.
+   *
+   * @param <T> the type of the parent class
+   * @param parentClass the parent class to find subclasses for
+   * @return an array of subclasses
+   * @since 10.0.0
+   */
   default <T> Array<Class<T>> findInherited(Class<T> parentClass) {
     MutableArray<Class<T>> result = MutableArray.ofType(Class.class);
     findInheritedTo(result, parentClass);
     return result;
   }
 
+  /**
+   * Finds all classes that inherit from the specified parent class and adds them to the container.
+   *
+   * @param <T> the type of the parent class
+   * @param container the container to add subclasses to
+   * @param parentClass the parent class to find subclasses for
+   * @since 10.0.0
+   */
   <T> void findInheritedTo(MutableArray<Class<T>> container, Class<T> parentClass);
 
+  /**
+   * Finds all classes annotated with the specified annotation.
+   *
+   * @param annotationClass the annotation class to search for
+   * @return an array of annotated classes
+   * @since 10.0.0
+   */
   default Array<Class<?>> findAnnotated(Class<? extends Annotation> annotationClass) {
     MutableArray<Class<?>> result = MutableArray.ofType(Class.class);
     findAnnotatedTo(result, annotationClass);
     return result;
   }
 
+  /**
+   * Finds all classes annotated with the specified annotation and adds them to the container.
+   *
+   * @param container the container to add annotated classes to
+   * @param annotationClass the annotation class to search for
+   * @since 10.0.0
+   */
   void findAnnotatedTo(MutableArray<Class<?>> container, Class<? extends Annotation> annotationClass);
 
+  /**
+   * Adds all found classes to the specified container.
+   *
+   * @param container the container to add classes to
+   * @since 10.0.0
+   */
   void foundClassesTo(MutableArray<Class<?>> container);
 
+  /**
+   * Adds all found resources to the specified container.
+   *
+   * @param container the container to add resources to
+   * @since 10.0.0
+   */
   void foundResourcesTo(MutableArray<String> container);
 
+  /**
+   * Returns all classes found during scanning.
+   *
+   * @return an array of found classes
+   * @since 10.0.0
+   */
   Array<Class<?>> foundClasses();
 
+  /**
+   * Returns all resources found during scanning.
+   *
+   * @return an array of found resource paths
+   * @since 10.0.0
+   */
   Array<String> foundResources();
 
+  /**
+   * Scans the classpath without any filter.
+   *
+   * @since 10.0.0
+   */
   default void scan() {
     scan(null);
   }
 
+  /**
+   * Scans the classpath with the specified filter.
+   *
+   * @param filter the filter to apply during scanning, or null for no filter
+   * @since 10.0.0
+   */
   void scan(@Nullable Predicate<String> filter);
 
+  /**
+   * Adds an additional path to scan.
+   *
+   * @param path the path to add
+   * @since 10.0.0
+   */
   void addAdditionalPath(String path);
 
+  /**
+   * Adds additional paths to scan.
+   *
+   * @param paths the paths to add
+   * @since 10.0.0
+   */
   void addAdditionalPaths(String[] paths);
 }