Extend/Update API part 11

.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-collections/src/main/java/javasabr/rlib/collections/array/ArrayIterationFunctions.java

@@ -2,8 +2,8 @@
 
 import java.util.function.BiConsumer;
 import java.util.function.BiPredicate;
+import javasabr.rlib.functions.BiObjLongConsumer;
 import javasabr.rlib.functions.ObjIntPredicate;
-import javasabr.rlib.functions.ObjObjLongConsumer;
 import javasabr.rlib.functions.TriConsumer;
 import org.jspecify.annotations.Nullable;
 
@@ -80,7 +80,7 @@ public interface ArrayIterationFunctions<E> {
    * @return this for method chaining
    * @since 10.0.0
    */
-  <A> ArrayIterationFunctions<E> forEach(A arg1, long arg2, ObjObjLongConsumer<? super E, A> consumer);
+  <A> ArrayIterationFunctions<E> forEach(A arg1, long arg2, BiObjLongConsumer<? super E, A> consumer);
 
   /**
    * Returns whether any element matches the filter predicate.

rlib-collections/src/main/java/javasabr/rlib/collections/array/impl/DefaultArrayIterationFunctions.java

@@ -5,8 +5,8 @@
 import javasabr.rlib.collections.array.ArrayIterationFunctions;
 import javasabr.rlib.collections.array.ReversedArgsArrayIterationFunctions;
 import javasabr.rlib.collections.array.UnsafeArray;
+import javasabr.rlib.functions.BiObjLongConsumer;
 import javasabr.rlib.functions.ObjIntPredicate;
-import javasabr.rlib.functions.ObjObjLongConsumer;
 import javasabr.rlib.functions.TriConsumer;
 import org.jspecify.annotations.Nullable;
 
@@ -64,7 +64,7 @@ public <F, S> ArrayIterationFunctions<E> forEach(F arg1, S arg2, TriConsumer<? s
   }
 
   @Override
-  public <F> ArrayIterationFunctions<E> forEach(F arg1, long arg2, ObjObjLongConsumer<? super E, F> consumer) {
+  public <F> ArrayIterationFunctions<E> forEach(F arg1, long arg2, BiObjLongConsumer<? super E, F> consumer) {
     @Nullable E[] wrapped = array.wrapped();
     int size = array.size();
     for (int i = 0; i < size; i++) {

rlib-collections/src/main/java/javasabr/rlib/collections/array/impl/ImmutableArray.java

@@ -81,7 +81,7 @@ public ImmutableArray(Class<? super E> type, E e1, E e2, E e3, E e4, E e5, E e6)
   @SafeVarargs
   public ImmutableArray(Class<? super E> type, E... elements) {
     super(type);
-    if (ArrayUtils.getComponentType(elements) == type) {
+    if (ArrayUtils.resolveComponentType(elements) == type) {
       this.wrapped = elements;
       return;
     }

rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableOperations.java

@@ -4,7 +4,7 @@
 import java.util.function.BiFunction;
 import java.util.function.Consumer;
 import java.util.function.Function;
-import javasabr.rlib.functions.BiObjToBooleanFunction;
+import javasabr.rlib.functions.BiObjToBoolFunction;
 import javasabr.rlib.functions.ObjIntFunction;
 import javasabr.rlib.functions.TriConsumer;
 import javasabr.rlib.functions.TriFunction;
@@ -73,7 +73,7 @@ public interface LockableOperations<S extends LockableSource> {
    * @return the boolean result
    * @since 10.0.0
    */
-  <A> boolean getBooleanInReadLock(A arg1, BiObjToBooleanFunction<S, A> function);
+  <A> boolean getBooleanInReadLock(A arg1, BiObjToBoolFunction<S, A> function);
 
   /**
    * Executes a consumer within a read lock with one argument.

rlib-collections/src/main/java/javasabr/rlib/collections/operation/impl/DefaultLockableOperations.java

@@ -6,7 +6,7 @@
 import java.util.function.Function;
 import javasabr.rlib.collections.operation.LockableOperations;
 import javasabr.rlib.collections.operation.LockableSource;
-import javasabr.rlib.functions.BiObjToBooleanFunction;
+import javasabr.rlib.functions.BiObjToBoolFunction;
 import javasabr.rlib.functions.ObjIntFunction;
 import javasabr.rlib.functions.TriConsumer;
 import javasabr.rlib.functions.TriFunction;
@@ -55,7 +55,7 @@ public <R, A, B> R getInReadLock(A arg1, B arg2, TriFunction<S, A, B, R> functio
   }
 
   @Override
-  public <A> boolean getBooleanInReadLock(A arg1, BiObjToBooleanFunction<S, A> function) {
+  public <A> boolean getBooleanInReadLock(A arg1, BiObjToBoolFunction<S, A> function) {
     long stamp = source.readLock();
     try {
       return function.apply(source, arg1);

rlib-common/build.gradle

@@ -5,4 +5,5 @@ plugins {
 
 dependencies {
   api projects.rlibLoggerApi
+  api projects.rlibFunctions
 }

rlib-common/src/main/java/javasabr/rlib/common/Copyable.java

@@ -1,5 +1,17 @@
 package javasabr.rlib.common;
 
+/**
+ * Represents an object that can create a copy of itself.
+ *
+ * @param <T> the type of the object to be copied
+ * @since 10.0.0
+ */
 public interface Copyable<T> {
+
+  /**
+   * Creates a copy of this object.
+   *
+   * @return a copy of this object
+   */
   T copy();
 }

rlib-common/src/main/java/javasabr/rlib/common/ThreadSafe.java

@@ -1,6 +1,11 @@
 package javasabr.rlib.common;
 
 /**
- * Interface to mark a class that it's a thread safe.
+ * Marker interface to indicate that a class is thread-safe.
+ * <p>
+ * Classes implementing this interface guarantee that their instances can be safely
+ * accessed by multiple threads concurrently without external synchronization.
+ *
+ * @since 10.0.0
  */
 public interface ThreadSafe {}