From a6c99ea1bc1bc0f4d21da7f2a52e1f3739a2f04f Mon Sep 17 00:00:00 2001
From: javasabr <javasabr@gmail.com>
Date: Fri, 6 Feb 2026 20:25:33 +0100
Subject: [PATCH] update javadoc for collection module

---
 .../rlib/collections/array/Array.java         | 285 ++++++++++++++----
 .../rlib/collections/array/ArrayBuilder.java  |  46 +++
 .../collections/array/ArrayCollectors.java    |  21 ++
 .../rlib/collections/array/ArrayFactory.java  |  50 +++
 .../array/ArrayIterationFunctions.java        |  68 +++++
 .../rlib/collections/array/IntArray.java      | 148 ++++++++-
 .../rlib/collections/array/LockableArray.java |  12 +
 .../rlib/collections/array/LongArray.java     | 149 ++++++++-
 .../rlib/collections/array/MutableArray.java  |  67 +++-
 .../collections/array/MutableIntArray.java    |  69 +++++
 .../collections/array/MutableLongArray.java   |  69 +++++
 .../ReversedArgsArrayIterationFunctions.java  |  44 +++
 .../rlib/collections/array/UnsafeArray.java   |  21 ++
 .../collections/array/UnsafeIntArray.java     |  21 ++
 .../collections/array/UnsafeLongArray.java    |  21 ++
 .../collections/array/UnsafeMutableArray.java |  42 +++
 .../array/UnsafeMutableIntArray.java          |  41 +++
 .../array/UnsafeMutableLongArray.java         |  41 +++
 .../rlib/collections/deque/DequeFactory.java  |  27 ++
 .../collections/dictionary/Dictionary.java    |  97 ++++++
 .../dictionary/DictionaryCollectors.java      |  26 ++
 .../dictionary/DictionaryFactory.java         |  63 ++++
 .../collections/dictionary/HashEntry.java     |  12 +
 .../dictionary/IntToRefDictionary.java        |  98 ++++++
 .../collections/dictionary/IntToRefEntry.java |  19 ++
 .../collections/dictionary/LinkedEntry.java   |  20 ++
 .../dictionary/LinkedHashEntry.java           |   8 +
 .../dictionary/LinkedHashIntToRefEntry.java   |   7 +
 .../dictionary/LinkedHashLongToRefEntry.java  |   7 +
 .../LockableRefToRefDictionary.java           |  13 +
 .../dictionary/LongToRefDictionary.java       |  98 ++++++
 .../dictionary/LongToRefEntry.java            |  20 ++
 .../dictionary/MutableIntToRefDictionary.java | 108 ++++++-
 .../MutableLongToRefDictionary.java           | 108 ++++++-
 .../dictionary/MutableRefToRefDictionary.java | 111 ++++++-
 .../rlib/collections/dictionary/RefEntry.java |  20 ++
 .../dictionary/RefToRefDictionary.java        | 122 +++++++-
 .../dictionary/RefToRefDictionaryBuilder.java |  44 ++-
 .../collections/dictionary/RefToRefEntry.java |  21 ++
 .../dictionary/UnsafeIntToRefDictionary.java  |  13 +
 .../dictionary/UnsafeLongToRefDictionary.java |  13 +
 .../UnsafeMutableIntToRefDictionary.java      |   7 +
 .../UnsafeMutableLongToRefDictionary.java     |   7 +
 .../UnsafeMutableRefToRefDictionary.java      |   8 +
 .../dictionary/UnsafeRefToRefDictionary.java  |  14 +
 .../operation/LockableOperations.java         | 108 +++++++
 .../collections/operation/LockableSource.java |  45 +++
 47 files changed, 2393 insertions(+), 86 deletions(-)

diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/Array.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/Array.java
index a40377d4..a1a0d465 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/Array.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/Array.java
@@ -15,49 +15,140 @@
 import org.jspecify.annotations.Nullable;
 
 /**
+ * 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>, Serializable, Cloneable {
 
+  /**
+   * Creates an empty immutable array of the specified type.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return an empty immutable array
+   * @since 10.0.0
+   */
   static <E> Array<E> empty(Class<? super E> type) {
     return new ImmutableArray<>(ClassUtils.unsafeCast(type));
   }
 
+  /**
+   * Creates a new builder for constructing an immutable array.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new array builder
+   * @since 10.0.0
+   */
   static <E> ArrayBuilder<E> builder(Class<? super E> type) {
     return new ArrayBuilder<>(type);
   }
-  
+
+  /**
+   * Creates an immutable array containing a single element.
+   *
+   * @param <E> the type of elements
+   * @param single the single element
+   * @return an immutable array containing the element
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E single) {
     @SuppressWarnings("unchecked")
     Class<E> type = (Class<E>) single.getClass();
     return new ImmutableArray<>(type, single);
   }
 
+  /**
+   * Creates an immutable array containing two elements.
+   *
+   * @param <E> the type of elements
+   * @param e1 the first element
+   * @param e2 the second element
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E e1, E e2) {
     Class<E> commonType = ClassUtils.commonType(e1, e2);
     return new ImmutableArray<>(commonType, e1, e2);
   }
 
+  /**
+   * Creates an immutable array containing three elements.
+   *
+   * @param <E> the type of elements
+   * @param e1 the first element
+   * @param e2 the second element
+   * @param e3 the third element
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E e1, E e2, E e3) {
     Class<E> commonType = ClassUtils.commonType(e1, e2, e3);
     return new ImmutableArray<>(commonType, e1, e2, e3);
   }
 
+  /**
+   * Creates an immutable array containing four elements.
+   *
+   * @param <E> the type of elements
+   * @param e1 the first element
+   * @param e2 the second element
+   * @param e3 the third element
+   * @param e4 the fourth element
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E e1, E e2, E e3, E e4) {
     Class<E> commonType = ClassUtils.commonType(e1, e2, e3, e4);
     return new ImmutableArray<>(commonType, e1, e2, e3, e4);
   }
 
+  /**
+   * Creates an immutable array containing five elements.
+   *
+   * @param <E> the type of elements
+   * @param e1 the first element
+   * @param e2 the second element
+   * @param e3 the third element
+   * @param e4 the fourth element
+   * @param e5 the fifth element
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E e1, E e2, E e3, E e4, E e5) {
     Class<E> commonType = ClassUtils.commonType(e1, e2, e3, e4, e5);
     return new ImmutableArray<>(commonType, e1, e2, e3, e4, e5);
   }
 
+  /**
+   * Creates an immutable array containing six elements.
+   *
+   * @param <E> the type of elements
+   * @param e1 the first element
+   * @param e2 the second element
+   * @param e3 the third element
+   * @param e4 the fourth element
+   * @param e5 the fifth element
+   * @param e6 the sixth element
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   static <E> Array<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
     Class<E> commonType = ClassUtils.commonType(e1, e2, e3, e4, e5, e6);
     return new ImmutableArray<>(commonType, e1, e2, e3, e4, e5, e6);
   }
 
+  /**
+   * Creates an immutable array containing the specified elements.
+   *
+   * @param <E> the type of elements
+   * @param elements the elements to include
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <E> Array<E> of(E... elements) {
     //noinspection unchecked
@@ -67,11 +158,29 @@ static <E> Array<E> of(E... elements) {
     return new ImmutableArray<>(type, elements);
   }
 
+  /**
+   * Creates an immutable array with explicit type containing the specified elements.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @param elements the elements to include
+   * @return an immutable array containing the elements
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <E> Array<E> typed(Class<? super E> type, E... elements) {
     return new ImmutableArray<>(type, elements);
   }
 
+  /**
+   * Creates an immutable array from present optional values.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @param elements the optional elements
+   * @return an immutable array containing present values
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <E> Array<E> optionals(Class<? super E> type, Optional<E>... elements) {
     return Stream
@@ -82,7 +191,13 @@ static <E> Array<E> optionals(Class<? super E> type, Optional<E>... elements) {
   }
 
   /**
-   * Creates array with the same element repeated 'count' times
+   * Creates an immutable array with the same element repeated specified times.
+   *
+   * @param <E> the type of elements
+   * @param element the element to repeat
+   * @param count the number of times to repeat
+   * @return an immutable array with repeated elements
+   * @since 10.0.0
    */
   static <E> Array<E> repeated(E element, int count) {
     @SuppressWarnings("unchecked")
@@ -92,6 +207,14 @@ static <E> Array<E> repeated(E element, int count) {
     return ImmutableArray.trustWrap(array);
   }
 
+  /**
+   * Creates an immutable copy of the specified array.
+   *
+   * @param <E> the type of elements
+   * @param array the array to copy
+   * @return an immutable copy of the array
+   * @since 10.0.0
+   */
   static <E> Array<E> copyOf(Array<E> array) {
     if (array instanceof ImmutableArray<E>) {
       return array;
@@ -99,6 +222,15 @@ static <E> Array<E> copyOf(Array<E> array) {
     return new ImmutableArray<>(array.type(), array.toArray());
   }
 
+  /**
+   * Creates an immutable array from the specified collection.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @param collection the collection to copy
+   * @return an immutable array containing the collection elements
+   * @since 10.0.0
+   */
   static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
     if (collection instanceof MutableArray<E> mutableArray) {
       return copyOf(mutableArray);
@@ -107,14 +239,21 @@ static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
     return ImmutableArray.trustWrap(array);
   }
 
+  /**
+   * Returns the component type of this array.
+   *
+   * @return the component type
+   * @since 10.0.0
+   */
   Class<E> type();
 
   /**
-   * Returns the number of elements in this array.  If this array
+   * Returns the number of elements in this array. If this array
    * contains more than {@code Integer.MAX_VALUE} elements, returns
    * {@code Integer.MAX_VALUE}.
    *
    * @return the number of elements in this array
+   * @since 10.0.0
    */
   int size();
 
@@ -125,14 +264,8 @@ static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
    * {@code Objects.equals(object, e)}.
    *
    * @param object element whose presence in this array is to be tested
-   * @return {@code true} if this array contains the specified
-   *         element
-   * @throws ClassCastException if the type of the specified element
-   *         is incompatible with this array
-   *         ({@linkplain Collection##optional-restrictions optional})
-   * @throws NullPointerException if the specified element is null and this
-   *         array does not permit null elements
-   *         ({@linkplain Collection##optional-restrictions optional})
+   * @return {@code true} if this array contains the specified element
+   * @since 10.0.0
    */
   boolean contains(@Nullable Object object);
 
@@ -140,19 +273,11 @@ static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
    * Returns {@code true} if this array contains all of the elements
    * in the specified array.
    *
-   * @param  array array to be checked for containment in this collection
+   * @param  array array to be checked for containment in this array
    * @return {@code true} if this array contains all of the elements
    *         in the specified array
-   * @throws ClassCastException if the types of one or more elements
-   *         in the specified array are incompatible with this
-   *         array
-   *         ({@linkplain Collection##optional-restrictions optional})
-   * @throws NullPointerException if the specified array contains one
-   *         or more null elements and this array does not permit null
-   *         elements
-   *         ({@linkplain Collection##optional-restrictions optional})
-   *         or if the specified collection is null.
    * @see    #contains(Object)
+   * @since 10.0.0
    */
   boolean containsAll(Array<?> array);
 
@@ -163,16 +288,8 @@ static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
    * @param  collection collection to be checked for containment in this array
    * @return {@code true} if this array contains all of the elements
    *         in the specified collection
-   * @throws ClassCastException if the types of one or more elements
-   *         in the specified collection are incompatible with this
-   *         collection
-   *         ({@linkplain Collection##optional-restrictions optional})
-   * @throws NullPointerException if the specified collection contains one
-   *         or more null elements and this array does not permit null
-   *         elements
-   *         ({@linkplain Collection##optional-restrictions optional})
-   *         or if the specified collection is null.
    * @see    #contains(Object)
+   * @since 10.0.0
    */
   boolean containsAll(Collection<?> collection);
 
@@ -180,36 +297,38 @@ static <E> Array<E> copyOf(Class<? super E> type, Collection<E> collection) {
    * Returns {@code true} if this array contains all of the elements
    * in the specified array.
    *
-   * @param  array array to be checked for containment in this collection
+   * @param  array array to be checked for containment in this array
    * @return {@code true} if this array contains all of the elements
    *         in the specified array
-   * @throws ClassCastException if the types of one or more elements
-   *         in the specified array are incompatible with this
-   *         array
-   *         ({@linkplain Collection##optional-restrictions optional})
-   * @throws NullPointerException if the specified array contains one
-   *         or more null elements and this array does not permit null
-   *         elements
-   *         ({@linkplain Collection##optional-restrictions optional})
-   *         or if the specified collection is null.
    * @see    #contains(Object)
+   * @since 10.0.0
    */
   boolean containsAll(Object[] array);
 
   /**
-   * Gets the first element of this array.
-
-   * @return the retrieved element or null
+   * Returns the first element of this array, or null if empty.
+   *
+   * @return the first element or null
+   * @since 10.0.0
    */
   @Nullable
   E first();
 
+  /**
+   * Returns the element at the specified index.
+   *
+   * @param index the index of the element to return
+   * @return the element at the specified index
+   * @throws IndexOutOfBoundsException if the index is out of range
+   * @since 10.0.0
+   */
   E get(int index);
 
   /**
-   * Gets the last element of this array.
-
-   * @return the retrieved element or null
+   * Returns the last element of this array, or null if empty.
+   *
+   * @return the last element or null
+   * @since 10.0.0
    */
   @Nullable
   E last();
@@ -220,44 +339,108 @@ default Iterator<E> iterator() {
   }
 
   /**
-   * @return the index of the object or -1.
+   * Returns the index of the first occurrence of the specified object.
+   *
+   * @param object the object to search for
+   * @return the index of the object or -1 if not found
+   * @since 10.0.0
    */
   int indexOf(@Nullable Object object);
 
   /**
-   * @return the index of the object or -1.
+   * Returns the index of the first element whose property matches the specified object.
+   *
+   * @param <T> the type of the property
+   * @param getter the function to extract the property
+   * @param object the object to match
+   * @return the index of the object or -1 if not found
+   * @since 10.0.0
    */
   <T> int indexOf(Function<E, T> getter, @Nullable Object object);
 
+  /**
+   * Returns the index of the last occurrence of the specified object.
+   *
+   * @param object the object to search for
+   * @return the index of the object or -1 if not found
+   * @since 10.0.0
+   */
   int lastIndexOf(@Nullable Object object);
 
+  /**
+   * Copies elements into the provided array.
+   *
+   * @param <T> the type of the array elements
+   * @param newArray the array to copy into
+   * @return the array with copied elements
+   * @since 10.0.0
+   */
   <T > T[] toArray(T[] newArray);
 
   /**
-   * Copy this array to the new array.
+   * Copies this array to a new array of the specified component type.
    *
    * @param <T> the type parameter
-   * @param componentType the type of the new array.
-   * @return the copied array.
+   * @param componentType the type of the new array
+   * @return the copied array
+   * @since 10.0.0
    */
   <T> T[] toArray(Class<T> componentType);
 
+  /**
+   * Returns {@code true} if this array contains no elements.
+   *
+   * @return {@code true} if this array is empty
+   * @since 10.0.0
+   */
   boolean isEmpty();
 
+  /**
+   * Returns a new array containing all elements.
+   *
+   * @return an array containing all elements
+   * @since 10.0.0
+   */
   E[] toArray();
 
+  /**
+   * Returns a string representation using the specified formatter.
+   *
+   * @param toString the function to convert elements to strings
+   * @return a string representation of this array
+   * @since 10.0.0
+   */
   String toString(Function<E, String> toString);
 
   /**
    * Returns a sequential {@code Stream} with this array as its source.
    *
    * @return a sequential {@code Stream} over the elements in this array
+   * @since 10.0.0
    */
   Stream<E> stream();
 
+  /**
+   * Returns iteration functions for this array.
+   *
+   * @return the iteration functions
+   * @since 10.0.0
+   */
   ArrayIterationFunctions<E> iterations();
 
+  /**
+   * Returns an unsafe view of this array providing direct access to internals.
+   *
+   * @return an unsafe view of this array
+   * @since 10.0.0
+   */
   UnsafeArray<E> asUnsafe();
 
+  /**
+   * Returns an unmodifiable list view of this array.
+   *
+   * @return an unmodifiable list view
+   * @since 10.0.0
+   */
   List<E> toList();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayBuilder.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayBuilder.java
index 06be898d..aa527f88 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayBuilder.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayBuilder.java
@@ -4,36 +4,82 @@
 import lombok.AccessLevel;
 import lombok.experimental.FieldDefaults;
 
+/**
+ * A builder for constructing immutable {@link Array} instances.
+ *
+ * @param <E> the type of elements in the array being built
+ * @since 10.0.0
+ */
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
 public final class ArrayBuilder<E> {
 
   MutableArray<E> elements;
 
+  /**
+   * Creates a new array builder with the specified component type.
+   *
+   * @param type the component type of the array
+   * @since 10.0.0
+   */
   public ArrayBuilder(Class<? super E> type) {
     this.elements = ArrayFactory.mutableArray(type);
   }
 
+  /**
+   * Adds an element to the array being built.
+   *
+   * @param element the element to add
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public ArrayBuilder<E> add(E element) {
     elements.add(element);
     return this;
   }
 
+  /**
+   * Adds multiple elements to the array being built.
+   *
+   * @param other the elements to add
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   @SafeVarargs
   public final ArrayBuilder<E> add(E... other) {
     elements.addAll(other);
     return this;
   }
 
+  /**
+   * Adds all elements from a collection to the array being built.
+   *
+   * @param other the collection of elements to add
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public ArrayBuilder<E> add(Collection<E> other) {
     elements.addAll(other);
     return this;
   }
 
+  /**
+   * Adds all elements from an array to the array being built.
+   *
+   * @param other the array of elements to add
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public ArrayBuilder<E> add(Array<E> other) {
     elements.addAll(other);
     return this;
   }
 
+  /**
+   * Builds and returns an immutable array containing all added elements.
+   *
+   * @return an immutable array containing all added elements
+   * @since 10.0.0
+   */
   public Array<E> build() {
     return Array.copyOf(elements);
   }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayCollectors.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayCollectors.java
index ce87c751..b4db250b 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayCollectors.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayCollectors.java
@@ -12,6 +12,11 @@
 import java.util.stream.Collector.Characteristics;
 import lombok.experimental.UtilityClass;
 
+/**
+ * Provides {@link Collector} implementations for collecting stream elements into {@link Array} instances.
+ *
+ * @since 10.0.0
+ */
 @UtilityClass
 public class ArrayCollectors {
 
@@ -96,10 +101,26 @@ public Set<Characteristics> characteristics() {
     };
   }
 
+  /**
+   * Returns a collector that accumulates elements into a mutable array.
+   *
+   * @param <T> the type of elements
+   * @param type the component type of the array
+   * @return a collector that collects elements into a mutable array
+   * @since 10.0.0
+   */
   public static <T> Collector<T, MutableArray<T>, MutableArray<T>> toMutableArray(Class<? super T> type) {
     return mutableCollector(type, ArrayFactory::mutableArray);
   }
 
+  /**
+   * Returns a collector that accumulates elements into an immutable array.
+   *
+   * @param <T> the type of elements
+   * @param type the component type of the array
+   * @return a collector that collects elements into an immutable array
+   * @since 10.0.0
+   */
   public static <T> Collector<T, MutableArray<T>, Array<T>> toArray(Class<? super T> type) {
     return collector(type, ArrayFactory::mutableArray);
   }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayFactory.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayFactory.java
index 1960983f..e7cd1af5 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayFactory.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayFactory.java
@@ -8,30 +8,80 @@
 import javasabr.rlib.common.util.ClassUtils;
 import lombok.experimental.UtilityClass;
 
+/**
+ * Factory for creating various array implementations.
+ *
+ * @since 10.0.0
+ */
 @UtilityClass
 public class ArrayFactory {
 
+  /**
+   * Creates a new mutable array of the specified type.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new mutable array
+   * @since 10.0.0
+   */
   public static <E> MutableArray<E> mutableArray(Class<? super E> type) {
     return new DefaultMutableArray<>(ClassUtils.unsafeCast(type));
   }
 
+  /**
+   * Creates a new mutable int array.
+   *
+   * @return a new mutable int array
+   * @since 10.0.0
+   */
   public static MutableIntArray mutableIntArray() {
     return new DefaultMutableIntArray();
   }
 
+  /**
+   * Creates a new mutable long array.
+   *
+   * @return a new mutable long array
+   * @since 10.0.0
+   */
   public static MutableLongArray mutableLongArray() {
     return new DefaultMutableLongArray();
   }
 
+  /**
+   * Creates a new mutable array of the specified type with initial capacity.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @param capacity the initial capacity
+   * @return a new mutable array
+   * @since 10.0.0
+   */
   public static <E> MutableArray<E> mutableArray(Class<? super E> type, int capacity) {
     return new DefaultMutableArray<>(ClassUtils.unsafeCast(type), capacity);
   }
 
 
+  /**
+   * Creates a new copy-on-modify array of the specified type.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new copy-on-modify array
+   * @since 10.0.0
+   */
   public static <E> MutableArray<E> copyOnModifyArray(Class<? super E> type) {
     return new CopyOnWriteMutableArray<>(type);
   }
 
+  /**
+   * Creates a new thread-safe array backed by a stamped lock.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new lockable array
+   * @since 10.0.0
+   */
   public static <E> LockableArray<E> stampedLockBasedArray(Class<? super E> type) {
     return new StampedLockBasedArray<>(type);
   }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayIterationFunctions.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayIterationFunctions.java
index 985d3af8..fdd7943a 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayIterationFunctions.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ArrayIterationFunctions.java
@@ -7,21 +7,89 @@
 import javasabr.rlib.functions.TriConsumer;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Provides iteration functions for arrays with support for additional arguments.
+ *
+ * @param <E> the type of elements in the array
+ * @since 10.0.0
+ */
 public interface ArrayIterationFunctions<E> {
 
+  /**
+   * Returns iteration functions with reversed argument order.
+   *
+   * @return reversed argument iteration functions
+   * @since 10.0.0
+   */
   ReversedArgsArrayIterationFunctions<E> reversedArgs();
 
+  /**
+   * Finds any element matching the filter predicate.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the filter
+   * @param filter the predicate to match elements
+   * @return the matching element or null
+   * @since 10.0.0
+   */
   @Nullable
   <A> E findAny(A arg1, BiPredicate<? super E, A> filter);
 
+  /**
+   * Finds any element matching the filter predicate with an int argument.
+   *
+   * @param arg1 the int argument to pass to the filter
+   * @param filter the predicate to match elements
+   * @return the matching element or null
+   * @since 10.0.0
+   */
   @Nullable
   E findAny(int arg1, ObjIntPredicate<? super E> filter);
 
+  /**
+   * Performs an action for each element with an additional argument.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the consumer
+   * @param consumer the action to perform
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   <A> ArrayIterationFunctions<E> forEach(A arg1, BiConsumer<? super E, A> consumer);
 
+  /**
+   * Performs an action for each element with two additional arguments.
+   *
+   * @param <A> the type of the first argument
+   * @param <B> the type of the second argument
+   * @param arg1 the first argument to pass to the consumer
+   * @param arg2 the second argument to pass to the consumer
+   * @param consumer the action to perform
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   <A, B> ArrayIterationFunctions<E> forEach(A arg1, B arg2, TriConsumer<? super E, A, B> consumer);
 
+  /**
+   * Performs an action for each element with an object and long argument.
+   *
+   * @param <A> the type of the first argument
+   * @param arg1 the first argument to pass to the consumer
+   * @param arg2 the long argument to pass to the consumer
+   * @param consumer the action to perform
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   <A> ArrayIterationFunctions<E> forEach(A arg1, long arg2, ObjObjLongConsumer<? super E, A> consumer);
 
+  /**
+   * Returns whether any element matches the filter predicate.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the filter
+   * @param filter the predicate to match elements
+   * @return true if any element matches
+   * @since 10.0.0
+   */
   <A> boolean anyMatch(A arg1, BiPredicate<? super E, A> filter);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/IntArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/IntArray.java
index 268f2381..12e468e3 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/IntArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/IntArray.java
@@ -7,78 +7,220 @@
 import javasabr.rlib.collections.array.impl.ImmutableIntArray;
 
 /**
+ * An immutable array interface for primitive int values.
+ *
  * @author JavaSaBr
+ * @since 10.0.0
  */
 public interface IntArray extends Iterable<Integer>, Serializable, Cloneable, RandomAccess {
 
   ImmutableIntArray EMPTY = new ImmutableIntArray();
 
+  /**
+   * Returns an empty immutable int array.
+   *
+   * @return an empty int array
+   * @since 10.0.0
+   */
   static IntArray empty() {
     return EMPTY;
   }
 
+  /**
+   * Creates an immutable int array containing a single value.
+   *
+   * @param e1 the value
+   * @return an immutable int array
+   * @since 10.0.0
+   */
   static IntArray of(int e1) {
     return new ImmutableIntArray(e1);
   }
 
+  /**
+   * Creates an immutable int array containing two values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @return an immutable int array
+   * @since 10.0.0
+   */
   static IntArray of(int e1, int e2) {
     return new ImmutableIntArray(e1, e2);
   }
 
+  /**
+   * Creates an immutable int array containing three values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @param e3 the third value
+   * @return an immutable int array
+   * @since 10.0.0
+   */
   static IntArray of(int e1, int e2, int e3) {
     return new ImmutableIntArray(e1, e2, e3);
   }
 
+  /**
+   * Creates an immutable int array containing four values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @param e3 the third value
+   * @param e4 the fourth value
+   * @return an immutable int array
+   * @since 10.0.0
+   */
   static IntArray of(int e1, int e2, int e3, int e4) {
     return new ImmutableIntArray(e1, e2, e3, e4);
   }
 
+  /**
+   * Creates an immutable int array containing the specified values.
+   *
+   * @param elements the values to include
+   * @return an immutable int array
+   * @since 10.0.0
+   */
   static IntArray of(int... elements) {
     return new ImmutableIntArray(elements);
   }
 
+  /**
+   * Creates an immutable copy of the specified int array.
+   *
+   * @param intArray the array to copy
+   * @return an immutable copy
+   * @since 10.0.0
+   */
   static IntArray copyOf(IntArray intArray) {
     return new ImmutableIntArray(intArray.toArray());
   }
 
+  /**
+   * Creates an immutable int array with the same value repeated.
+   *
+   * @param value the value to repeat
+   * @param count the number of times to repeat
+   * @return an immutable int array with repeated values
+   * @since 10.0.0
+   */
   static IntArray repeated(int value, int count) {
     int[] values = new int[count];
     Arrays.fill(values, value);
     return new ImmutableIntArray(values);
   }
 
+  /**
+   * Returns the number of elements in this array.
+   *
+   * @return the number of elements
+   * @since 10.0.0
+   */
   int size();
 
+  /**
+   * Returns whether this array contains the specified value.
+   *
+   * @param value the value to search for
+   * @return true if the array contains the value
+   * @since 10.0.0
+   */
   boolean contains(int value);
 
+  /**
+   * Returns whether this array contains all values from the specified array.
+   *
+   * @param array the array of values to check
+   * @return true if all values are contained
+   * @since 10.0.0
+   */
   boolean containsAll(IntArray array);
 
+  /**
+   * Returns whether this array contains all values from the specified array.
+   *
+   * @param array the array of values to check
+   * @return true if all values are contained
+   * @since 10.0.0
+   */
   boolean containsAll(int[] array);
 
   /**
-   * @return the first element or {@link java.util.NoSuchElementException}
+   * Returns the first element.
+   *
+   * @return the first element
+   * @throws java.util.NoSuchElementException if the array is empty
+   * @since 10.0.0
    */
   int first();
 
+  /**
+   * Returns the element at the specified index.
+   *
+   * @param index the index of the element
+   * @return the element at the index
+   * @since 10.0.0
+   */
   int get(int index);
 
   /**
-   * @return the last element or {@link java.util.NoSuchElementException}
+   * Returns the last element.
+   *
+   * @return the last element
+   * @throws java.util.NoSuchElementException if the array is empty
+   * @since 10.0.0
    */
   int last();
 
   /**
-   * @return the index of the value or -1.
+   * Returns the index of the first occurrence of the specified value.
+   *
+   * @param value the value to search for
+   * @return the index of the value or -1 if not found
+   * @since 10.0.0
    */
   int indexOf(int value);
 
+  /**
+   * Returns the index of the last occurrence of the specified value.
+   *
+   * @param value the value to search for
+   * @return the index of the value or -1 if not found
+   * @since 10.0.0
+   */
   int lastIndexOf(int value);
 
+  /**
+   * Returns whether this array is empty.
+   *
+   * @return true if empty
+   * @since 10.0.0
+   */
   boolean isEmpty();
 
+  /**
+   * Returns a new primitive int array containing all elements.
+   *
+   * @return an int array
+   * @since 10.0.0
+   */
   int[] toArray();
 
+  /**
+   * Returns a sequential stream of int values.
+   *
+   * @return an IntStream
+   * @since 10.0.0
+   */
   IntStream stream();
 
+  /**
+   * Returns an unsafe view providing direct access to internals.
+   *
+   * @return an unsafe view
+   * @since 10.0.0
+   */
   UnsafeIntArray asUnsafe();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/LockableArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/LockableArray.java
index 735d6977..e170d559 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/LockableArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/LockableArray.java
@@ -4,7 +4,19 @@
 import javasabr.rlib.collections.operation.LockableSource;
 import javasabr.rlib.common.ThreadSafe;
 
+/**
+ * A thread-safe mutable array that provides locking operations for concurrent access.
+ *
+ * @param <E> the type of elements in this array
+ * @since 10.0.0
+ */
 public interface LockableArray<E> extends MutableArray<E>, LockableSource, ThreadSafe {
 
+  /**
+   * Returns lockable operations for performing thread-safe operations on this array.
+   *
+   * @return lockable operations
+   * @since 10.0.0
+   */
   LockableOperations<LockableArray<E>> operations();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/LongArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/LongArray.java
index 10db626e..f7aa7467 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/LongArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/LongArray.java
@@ -1,3 +1,4 @@
+
 package javasabr.rlib.collections.array;
 
 import java.io.Serializable;
@@ -7,78 +8,220 @@
 import javasabr.rlib.collections.array.impl.ImmutableLongArray;
 
 /**
+ * An immutable array interface for primitive long values.
+ *
  * @author JavaSaBr
+ * @since 10.0.0
  */
 public interface LongArray extends Iterable<Long>, Serializable, Cloneable, RandomAccess {
 
   ImmutableLongArray EMPTY = new ImmutableLongArray();
 
+  /**
+   * Returns an empty immutable long array.
+   *
+   * @return an empty long array
+   * @since 10.0.0
+   */
   static LongArray empty() {
     return EMPTY;
   }
 
+  /**
+   * Creates an immutable long array containing a single value.
+   *
+   * @param e1 the value
+   * @return an immutable long array
+   * @since 10.0.0
+   */
   static LongArray of(long e1) {
     return new ImmutableLongArray(e1);
   }
 
+  /**
+   * Creates an immutable long array containing two values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @return an immutable long array
+   * @since 10.0.0
+   */
   static LongArray of(long e1, long e2) {
     return new ImmutableLongArray(e1, e2);
   }
 
+  /**
+   * Creates an immutable long array containing three values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @param e3 the third value
+   * @return an immutable long array
+   * @since 10.0.0
+   */
   static LongArray of(long e1, long e2, long e3) {
     return new ImmutableLongArray(e1, e2, e3);
   }
 
+  /**
+   * Creates an immutable long array containing four values.
+   *
+   * @param e1 the first value
+   * @param e2 the second value
+   * @param e3 the third value
+   * @param e4 the fourth value
+   * @return an immutable long array
+   * @since 10.0.0
+   */
   static LongArray of(long e1, long e2, long e3, long e4) {
     return new ImmutableLongArray(e1, e2, e3, e4);
   }
 
+  /**
+   * Creates an immutable long array containing the specified values.
+   *
+   * @param elements the values to include
+   * @return an immutable long array
+   * @since 10.0.0
+   */
   static LongArray of(long... elements) {
     return new ImmutableLongArray(elements);
   }
 
+  /**
+   * Creates an immutable copy of the specified long array.
+   *
+   * @param intArray the array to copy
+   * @return an immutable copy
+   * @since 10.0.0
+   */
   static LongArray copyOf(LongArray intArray) {
     return new ImmutableLongArray(intArray.toArray());
   }
 
+  /**
+   * Creates an immutable long array with the same value repeated.
+   *
+   * @param value the value to repeat
+   * @param count the number of times to repeat
+   * @return an immutable long array with repeated values
+   * @since 10.0.0
+   */
   static LongArray repeated(long value, int count) {
     long[] values = new long[count];
     Arrays.fill(values, value);
     return new ImmutableLongArray(values);
   }
 
+  /**
+   * Returns the number of elements in this array.
+   *
+   * @return the number of elements
+   * @since 10.0.0
+   */
   int size();
 
+  /**
+   * Returns whether this array contains the specified value.
+   *
+   * @param value the value to search for
+   * @return true if the array contains the value
+   * @since 10.0.0
+   */
   boolean contains(long value);
 
+  /**
+   * Returns whether this array contains all values from the specified array.
+   *
+   * @param array the array of values to check
+   * @return true if all values are contained
+   * @since 10.0.0
+   */
   boolean containsAll(LongArray array);
 
+  /**
+   * Returns whether this array contains all values from the specified array.
+   *
+   * @param array the array of values to check
+   * @return true if all values are contained
+   * @since 10.0.0
+   */
   boolean containsAll(long[] array);
 
   /**
-   * @return the first element or {@link java.util.NoSuchElementException}
+   * Returns the first element.
+   *
+   * @return the first element
+   * @throws java.util.NoSuchElementException if the array is empty
+   * @since 10.0.0
    */
   long first();
 
+  /**
+   * Returns the element at the specified index.
+   *
+   * @param index the index of the element
+   * @return the element at the index
+   * @since 10.0.0
+   */
   long get(int index);
 
   /**
-   * @return the last element or {@link java.util.NoSuchElementException}
+   * Returns the last element.
+   *
+   * @return the last element
+   * @throws java.util.NoSuchElementException if the array is empty
+   * @since 10.0.0
    */
   long last();
 
   /**
-   * @return the index of the value or -1.
+   * Returns the index of the first occurrence of the specified value.
+   *
+   * @param value the value to search for
+   * @return the index of the value or -1 if not found
+   * @since 10.0.0
    */
   int indexOf(long value);
 
+  /**
+   * Returns the index of the last occurrence of the specified value.
+   *
+   * @param value the value to search for
+   * @return the index of the value or -1 if not found
+   * @since 10.0.0
+   */
   int lastIndexOf(long value);
 
+  /**
+   * Returns whether this array is empty.
+   *
+   * @return true if empty
+   * @since 10.0.0
+   */
   boolean isEmpty();
 
+  /**
+   * Returns a new primitive long array containing all elements.
+   *
+   * @return a long array
+   * @since 10.0.0
+   */
   long[] toArray();
 
+  /**
+   * Returns a sequential stream of long values.
+   *
+   * @return a LongStream
+   * @since 10.0.0
+   */
   LongStream stream();
 
+  /**
+   * Returns an unsafe view providing direct access to internals.
+   *
+   * @return an unsafe view
+   * @since 10.0.0
+   */
   UnsafeLongArray asUnsafe();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableArray.java
index 66d3d1c0..8ef26de2 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableArray.java
@@ -8,25 +8,71 @@
 import java.util.stream.Stream;
 import javasabr.rlib.collections.array.impl.DefaultMutableArray;
 
+/**
+ * A mutable array interface that extends {@link Array} with modification operations.
+ *
+ * @param <E> the type of elements in this array
+ * @since 10.0.0
+ */
 public interface MutableArray<E> extends Array<E>, Collection<E> {
 
+  /**
+   * Creates a new mutable array of the specified type.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new mutable array
+   * @since 10.0.0
+   */
   static <E> MutableArray<E> ofType(Class<? super E> type) {
     return new DefaultMutableArray<>(type);
   }
 
+  /**
+   * Adds all elements from the specified array.
+   *
+   * @param array the array to add elements from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(Array<? extends E> array);
 
+  /**
+   * Adds all elements from the specified mutable array.
+   *
+   * @param array the array to add elements from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   default boolean addAll(MutableArray<? extends E> array) {
     return addAll((Array<? extends E>) array);
   }
 
+  /**
+   * Adds all elements from the specified Java array.
+   *
+   * @param array the array to add elements from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(E[] array);
 
   /**
+   * Removes the element at the specified index.
+   *
+   * @param index the index of the element to remove
    * @return the element previously at the specified position
+   * @since 10.0.0
    */
   E remove(int index);
 
+  /**
+   * Replaces the element at the specified index.
+   *
+   * @param index the index of the element to replace
+   * @param element the new element
+   * @since 10.0.0
+   */
   void replace(int index, E element);
 
   @Override
@@ -47,10 +93,27 @@ default void forEach(Consumer<? super E> action) {
     Array.super.forEach(action);
   }
 
+  /**
+   * Returns an unsafe mutable view of this array.
+   *
+   * @return an unsafe mutable view
+   * @since 10.0.0
+   */
   @Override
   UnsafeMutableArray<E> asUnsafe();
-  
+
+  /**
+   * Sorts this array using natural ordering.
+   *
+   * @since 10.0.0
+   */
   void sort();
-  
+
+  /**
+   * Sorts this array using the specified comparator.
+   *
+   * @param comparator the comparator to determine element order
+   * @since 10.0.0
+   */
   void sort(Comparator<E> comparator);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableIntArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableIntArray.java
index d119cd65..f7a3c371 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableIntArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableIntArray.java
@@ -1,28 +1,97 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * A mutable array interface for primitive int values.
+ *
+ * @since 10.0.0
+ */
 public interface MutableIntArray extends IntArray {
 
+  /**
+   * Adds a value to this array.
+   *
+   * @param value the value to add
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean add(int value);
 
+  /**
+   * Adds all values from the specified int array.
+   *
+   * @param array the array to add values from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(IntArray array);
 
+  /**
+   * Adds all values from the specified primitive int array.
+   *
+   * @param array the array to add values from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(int[] array);
 
   /**
+   * Removes the element at the specified index.
+   *
+   * @param index the index of the element to remove
    * @return the element previously at the specified position
+   * @since 10.0.0
    */
   int removeByIndex(int index);
 
+  /**
+   * Removes the first occurrence of the specified value.
+   *
+   * @param value the value to remove
+   * @return true if this array contained the value
+   * @since 10.0.0
+   */
   boolean remove(int value);
 
+  /**
+   * Removes all values that are contained in the specified array.
+   *
+   * @param array the array of values to remove
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean removeAll(IntArray array);
 
+  /**
+   * Removes all values that are contained in the specified array.
+   *
+   * @param array the array of values to remove
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean removeAll(int[] array);
 
+  /**
+   * Replaces the value at the specified index.
+   *
+   * @param index the index of the value to replace
+   * @param value the new value
+   * @since 10.0.0
+   */
   void replace(int index, int value);
 
+  /**
+   * Removes all values from this array.
+   *
+   * @since 10.0.0
+   */
   void clear();
 
+  /**
+   * Returns an unsafe mutable view of this array.
+   *
+   * @return an unsafe mutable view
+   * @since 10.0.0
+   */
   @Override
   UnsafeMutableIntArray asUnsafe();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableLongArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableLongArray.java
index dfea7d28..8da91528 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableLongArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableLongArray.java
@@ -1,28 +1,97 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * A mutable array interface for primitive long values.
+ *
+ * @since 10.0.0
+ */
 public interface MutableLongArray extends LongArray {
 
+  /**
+   * Adds a value to this array.
+   *
+   * @param value the value to add
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean add(long value);
 
+  /**
+   * Adds all values from the specified long array.
+   *
+   * @param array the array to add values from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(LongArray array);
 
+  /**
+   * Adds all values from the specified primitive long array.
+   *
+   * @param array the array to add values from
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean addAll(long[] array);
 
   /**
+   * Removes the element at the specified index.
+   *
+   * @param index the index of the element to remove
    * @return the element previously at the specified position
+   * @since 10.0.0
    */
   long removeByIndex(int index);
 
+  /**
+   * Removes the first occurrence of the specified value.
+   *
+   * @param value the value to remove
+   * @return true if this array contained the value
+   * @since 10.0.0
+   */
   boolean remove(long value);
 
+  /**
+   * Removes all values that are contained in the specified array.
+   *
+   * @param array the array of values to remove
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean removeAll(LongArray array);
 
+  /**
+   * Removes all values that are contained in the specified array.
+   *
+   * @param array the array of values to remove
+   * @return true if this array changed as a result
+   * @since 10.0.0
+   */
   boolean removeAll(long[] array);
 
+  /**
+   * Replaces the value at the specified index.
+   *
+   * @param index the index of the value to replace
+   * @param value the new value
+   * @since 10.0.0
+   */
   void replace(int index, long value);
 
+  /**
+   * Removes all values from this array.
+   *
+   * @since 10.0.0
+   */
   void clear();
 
+  /**
+   * Returns an unsafe mutable view of this array.
+   *
+   * @return an unsafe mutable view
+   * @since 10.0.0
+   */
   @Override
   UnsafeMutableLongArray asUnsafe();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ReversedArgsArrayIterationFunctions.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ReversedArgsArrayIterationFunctions.java
index b01e44af..30f6564c 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/ReversedArgsArrayIterationFunctions.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/ReversedArgsArrayIterationFunctions.java
@@ -5,14 +5,58 @@
 import javasabr.rlib.functions.TriConsumer;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Provides iteration functions for arrays with reversed argument order in callbacks.
+ *
+ * @param <E> the type of elements in the array
+ * @since 10.0.0
+ */
 public interface ReversedArgsArrayIterationFunctions<E> {
 
+  /**
+   * Finds any element matching the filter predicate with reversed argument order.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the filter
+   * @param filter the predicate to match elements (argument first, then element)
+   * @return the matching element or null
+   * @since 10.0.0
+   */
   @Nullable
   <A> E findAny(A arg1, BiPredicate<A, ? super E> filter);
 
+  /**
+   * Performs an action for each element with reversed argument order.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the consumer
+   * @param consumer the action to perform (argument first, then element)
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   <A> ReversedArgsArrayIterationFunctions<E> forEach(A arg1, BiConsumer<A, ? super E> consumer);
 
+  /**
+   * Performs an action for each element with two additional arguments in reversed order.
+   *
+   * @param <A> the type of the first argument
+   * @param <B> the type of the second argument
+   * @param arg1 the first argument to pass to the consumer
+   * @param arg2 the second argument to pass to the consumer
+   * @param consumer the action to perform (arguments first, then element)
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   <A, B> ReversedArgsArrayIterationFunctions<E> forEach(A arg1, B arg2, TriConsumer<A, B, ? super E> consumer);
 
+  /**
+   * Returns whether any element matches the filter predicate with reversed argument order.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument to pass to the filter
+   * @param filter the predicate to match elements (argument first, then element)
+   * @return true if any element matches
+   * @since 10.0.0
+   */
   <A> boolean anyMatch(A arg1, BiPredicate<A, ? super E> filter);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeArray.java
index eea2c7df..2e90748b 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeArray.java
@@ -2,8 +2,29 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An unsafe view of an array providing direct access to internal data structures.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @param <E> the type of elements in this array
+ * @since 10.0.0
+ */
 public interface UnsafeArray<E> extends Array<E> {
+
+  /**
+   * Returns the internal backing array.
+   *
+   * @return the backing array or null
+   * @since 10.0.0
+   */
   @Nullable E[] wrapped();
 
+  /**
+   * Returns the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element
+   * @return the element at the index
+   * @since 10.0.0
+   */
   E unsafeGet(int index);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeIntArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeIntArray.java
index d456511c..26479328 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeIntArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeIntArray.java
@@ -1,6 +1,27 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * An unsafe view of an int array providing direct access to internal data structures.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @since 10.0.0
+ */
 public interface UnsafeIntArray extends IntArray {
+
+  /**
+   * Returns the internal backing array.
+   *
+   * @return the backing array
+   * @since 10.0.0
+   */
   int[] wrapped();
+
+  /**
+   * Returns the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element
+   * @return the element at the index
+   * @since 10.0.0
+   */
   int unsafeGet(int index);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeLongArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeLongArray.java
index 35668235..ac7c1a13 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeLongArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeLongArray.java
@@ -1,6 +1,27 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * An unsafe view of a long array providing direct access to internal data structures.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @since 10.0.0
+ */
 public interface UnsafeLongArray extends LongArray {
+
+  /**
+   * Returns the internal backing array.
+   *
+   * @return the backing array
+   * @since 10.0.0
+   */
   long[] wrapped();
+
+  /**
+   * Returns the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element
+   * @return the element at the index
+   * @since 10.0.0
+   */
   long unsafeGet(int index);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableArray.java
index 7da5a8b7..ff2297c7 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableArray.java
@@ -1,14 +1,56 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * An unsafe mutable view of an array providing direct modification operations.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @param <E> the type of elements in this array
+ * @since 10.0.0
+ */
 public interface UnsafeMutableArray<E> extends UnsafeArray<E>, MutableArray<E> {
 
+  /**
+   * Prepares internal storage for the expected size to avoid reallocations.
+   *
+   * @param expectedSize the expected number of elements
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableArray<E> prepareForSize(int expectedSize);
 
+  /**
+   * Adds an element without triggering copy-on-write or other safety mechanisms.
+   *
+   * @param element the element to add
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableArray<E> unsafeAdd(E element);
 
+  /**
+   * Removes the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element to remove
+   * @return the removed element
+   * @since 10.0.0
+   */
   E unsafeRemove(int index);
 
+  /**
+   * Sets the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element to set
+   * @param element the new element
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableArray<E> unsafeSet(int index, E element);
 
+  /**
+   * Trims the internal storage to match the current size.
+   *
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableArray<E> trimToSize();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableIntArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableIntArray.java
index 0274df9e..4a74dd1c 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableIntArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableIntArray.java
@@ -1,14 +1,55 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * An unsafe mutable view of an int array providing direct modification operations.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @since 10.0.0
+ */
 public interface UnsafeMutableIntArray extends UnsafeIntArray, MutableIntArray {
 
+  /**
+   * Prepares internal storage for the expected size to avoid reallocations.
+   *
+   * @param expectedSize the expected number of elements
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableIntArray prepareForSize(int expectedSize);
 
+  /**
+   * Adds a value without triggering safety mechanisms.
+   *
+   * @param value the value to add
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableIntArray unsafeAdd(int value);
 
+  /**
+   * Removes the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element to remove
+   * @return the removed value
+   * @since 10.0.0
+   */
   int unsafeRemoveByInex(int index);
 
+  /**
+   * Sets the value at the specified index without bounds checking.
+   *
+   * @param index the index of the value to set
+   * @param value the new value
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableIntArray unsafeSet(int index, int value);
 
+  /**
+   * Trims the internal storage to match the current size.
+   *
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableIntArray trimToSize();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableLongArray.java b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableLongArray.java
index a78f81d0..9f26bd1c 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableLongArray.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/array/UnsafeMutableLongArray.java
@@ -1,14 +1,55 @@
 package javasabr.rlib.collections.array;
 
+/**
+ * An unsafe mutable view of a long array providing direct modification operations.
+ * Use with caution as modifications may violate array invariants.
+ *
+ * @since 10.0.0
+ */
 public interface UnsafeMutableLongArray extends UnsafeLongArray, MutableLongArray {
 
+  /**
+   * Prepares internal storage for the expected size to avoid reallocations.
+   *
+   * @param expectedSize the expected number of elements
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableLongArray prepareForSize(int expectedSize);
 
+  /**
+   * Adds a value without triggering safety mechanisms.
+   *
+   * @param value the value to add
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableLongArray unsafeAdd(long value);
 
+  /**
+   * Removes the element at the specified index without bounds checking.
+   *
+   * @param index the index of the element to remove
+   * @return the removed value
+   * @since 10.0.0
+   */
   long unsafeRemoveByInex(int index);
 
+  /**
+   * Sets the value at the specified index without bounds checking.
+   *
+   * @param index the index of the value to set
+   * @param value the new value
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableLongArray unsafeSet(int index, long value);
 
+  /**
+   * Trims the internal storage to match the current size.
+   *
+   * @return this for method chaining
+   * @since 10.0.0
+   */
   UnsafeMutableLongArray trimToSize();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/deque/DequeFactory.java b/rlib-collections/src/main/java/javasabr/rlib/collections/deque/DequeFactory.java
index f07a3c79..c713797f 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/deque/DequeFactory.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/deque/DequeFactory.java
@@ -6,19 +6,46 @@
 import lombok.experimental.UtilityClass;
 
 /**
+ * Factory for creating various deque implementations.
+ *
  * @author JavaSaBr
+ * @since 10.0.0
  */
 @UtilityClass
 public class DequeFactory {
 
+  /**
+   * Creates a new deque backed by a linked list.
+   *
+   * @param <E> the type of elements
+   * @return a new linked list based deque
+   * @since 10.0.0
+   */
   public static <E> Deque<E> linkedListBased() {
     return new DefaultLinkedListBasedDeque<>();
   }
 
+  /**
+   * Creates a new deque backed by an array.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @return a new array based deque
+   * @since 10.0.0
+   */
   public static <E> Deque<E> arrayBasedBased(Class<? super E> type) {
     return new DefaultArrayBasedDeque<>(type);
   }
 
+  /**
+   * Creates a new deque backed by an array with initial capacity.
+   *
+   * @param <E> the type of elements
+   * @param type the component type of the array
+   * @param capacity the initial capacity
+   * @return a new array based deque
+   * @since 10.0.0
+   */
   public static <E> Deque<E> arrayBasedBased(Class<? super E> type, int capacity) {
     return new DefaultArrayBasedDeque<>(type, capacity);
   }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/Dictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/Dictionary.java
index f6a12b91..1ce49315 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/Dictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/Dictionary.java
@@ -7,34 +7,131 @@
 import org.jspecify.annotations.Nullable;
 
 /**
+ * A base interface for dictionary (map-like) data structures.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
  * @author JavaSaBr
+ * @since 10.0.0
  */
 public interface Dictionary<K, V> extends Iterable<V> {
 
+  /**
+   * Returns whether this dictionary contains the specified key.
+   *
+   * @param key the key to check
+   * @return true if the key is present
+   * @since 10.0.0
+   */
   boolean containsKey(K key);
 
+  /**
+   * Returns whether this dictionary contains the specified value.
+   *
+   * @param value the value to check
+   * @return true if the value is present
+   * @since 10.0.0
+   */
   boolean containsValue(V value);
 
+  /**
+   * Returns whether this dictionary is empty.
+   *
+   * @return true if empty
+   * @since 10.0.0
+   */
   boolean isEmpty();
 
+  /**
+   * Returns the number of key-value mappings.
+   *
+   * @return the number of mappings
+   * @since 10.0.0
+   */
   int size();
 
+  /**
+   * Returns the value associated with the specified key.
+   *
+   * @param key the key
+   * @return the value or null if not found
+   * @since 10.0.0
+   */
   @Nullable
   V get(K key);
 
+  /**
+   * Returns an optional containing the value for the specified key.
+   *
+   * @param key the key
+   * @return an optional with the value
+   * @since 10.0.0
+   */
   Optional<V> getOptional(K key);
 
+  /**
+   * Returns the value for the key, or a default value if not found.
+   *
+   * @param key the key
+   * @param def the default value
+   * @return the value or the default
+   * @since 10.0.0
+   */
   V getOrDefault(K key, V def);
 
+  /**
+   * Collects all keys into the provided collection.
+   *
+   * @param <C> the collection type
+   * @param container the collection to add keys to
+   * @return the container with added keys
+   * @since 10.0.0
+   */
   <C extends Collection<K>> C keys(C container);
 
+  /**
+   * Collects all keys into the provided mutable array.
+   *
+   * @param container the array to add keys to
+   * @return the container with added keys
+   * @since 10.0.0
+   */
   MutableArray<K> keys(MutableArray<K> container);
 
+  /**
+   * Returns all keys as an immutable array.
+   *
+   * @param type the type of keys
+   * @return an array of keys
+   * @since 10.0.0
+   */
   Array<K> keys(Class<K> type);
 
+  /**
+   * Collects all values into the provided collection.
+   *
+   * @param <C> the collection type
+   * @param container the collection to add values to
+   * @return the container with added values
+   * @since 10.0.0
+   */
   <C extends Collection<V>> C values(C container);
 
+  /**
+   * Collects all values into the provided mutable array.
+   *
+   * @param container the array to add values to
+   * @return the container with added values
+   * @since 10.0.0
+   */
   MutableArray<V> values(MutableArray<V> container);
 
+  /**
+   * Returns all values as an immutable array.
+   *
+   * @param type the type of values
+   * @return an array of values
+   * @since 10.0.0
+   */
   Array<V> values(Class<V> type);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryCollectors.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryCollectors.java
index d93d13a2..ef8f8998 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryCollectors.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryCollectors.java
@@ -18,6 +18,11 @@
 import lombok.experimental.FieldDefaults;
 import lombok.experimental.UtilityClass;
 
+/**
+ * Provides {@link Collector} implementations for collecting stream elements into {@link RefToRefDictionary} instances.
+ *
+ * @since 10.0.0
+ */
 @UtilityClass
 public class DictionaryCollectors {
 
@@ -44,6 +49,16 @@ static class CollectorImpl<T, A, R> implements Collector<T, A, R> {
     }
   }
 
+  /**
+   * Returns a collector that accumulates elements into a dictionary using the element as the value.
+   *
+   * @param <T> the type of input elements
+   * @param <K> the type of keys
+   * @param <U> unused type parameter
+   * @param keyMapper the function to extract keys
+   * @return a collector that collects elements into a dictionary
+   * @since 10.0.0
+   */
   public static <T, K, U> Collector<T, MutableRefToRefDictionary<K, T>, RefToRefDictionary<K, T>> toRefToRefDictionary(
       Function<? super T, ? extends K> keyMapper) {
     return new CollectorImpl<>(
@@ -54,6 +69,17 @@ public static <T, K, U> Collector<T, MutableRefToRefDictionary<K, T>, RefToRefDi
         CH_ID);
   }
 
+  /**
+   * Returns a collector that accumulates elements into a dictionary.
+   *
+   * @param <T> the type of input elements
+   * @param <K> the type of keys
+   * @param <U> the type of values
+   * @param keyMapper the function to extract keys
+   * @param valueMapper the function to extract values
+   * @return a collector that collects elements into a dictionary
+   * @since 10.0.0
+   */
   public static <T, K, U> Collector<T, MutableRefToRefDictionary<K, U>, RefToRefDictionary<K, U>> toRefToRefDictionary(
       Function<? super T, ? extends K> keyMapper,
       Function<? super T, ? extends U> valueMapper) {
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryFactory.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryFactory.java
index e18b13ae..e6321315 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryFactory.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/DictionaryFactory.java
@@ -7,34 +7,97 @@
 import javasabr.rlib.collections.dictionary.impl.gc.optimized.GcOptimizedMutableHashBasedIntToRefDictionary;
 import lombok.experimental.UtilityClass;
 
+/**
+ * Factory for creating various dictionary implementations.
+ *
+ * @since 10.0.0
+ */
 @UtilityClass
 public class DictionaryFactory {
+
+  /**
+   * Creates a new mutable reference-to-reference dictionary.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   public static <K, V> MutableRefToRefDictionary<K, V> mutableRefToRefDictionary() {
     return new DefaultMutableHashBasedRefToRefDictionary<>();
   }
 
+  /**
+   * Creates a new mutable int-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   public static <V> MutableIntToRefDictionary<V> mutableIntToRefDictionary() {
     return new DefaultMutableHashBasedIntToRefDictionary<>();
   }
 
+  /**
+   * Creates a new GC-optimized mutable int-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @return a new GC-optimized mutable dictionary
+   * @since 10.0.0
+   */
   public static <V> MutableIntToRefDictionary<V> gcOptimizedIntToRefDictionary() {
     return new GcOptimizedMutableHashBasedIntToRefDictionary<>();
   }
 
+  /**
+   * Creates a new mutable long-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   public static <V> MutableLongToRefDictionary<V> mutableLongToRefDictionary() {
     return new DefaultMutableHashBasedLongToRefDictionary<>();
   }
 
+  /**
+   * Creates a new mutable reference-to-reference dictionary with explicit types.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param keyType the key type (unused, for type inference)
+   * @param valueType the value type (unused, for type inference)
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   public static <K, V> MutableRefToRefDictionary<K, V> mutableRefToRefDictionary(
       Class<? super K> keyType,
       Class<? super V> valueType) {
     return new DefaultMutableHashBasedRefToRefDictionary<>();
   }
 
+  /**
+   * Creates a new thread-safe dictionary backed by a stamped lock.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @return a new lockable dictionary
+   * @since 10.0.0
+   */
   public static <K, V> LockableRefToRefDictionary<K, V> stampedLockBasedRefToRefDictionary() {
     return new StampedLockBasedHashBasedRefToRefDictionary<>();
   }
 
+  /**
+   * Creates a new thread-safe dictionary backed by a stamped lock with explicit types.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param keyType the key type (unused, for type inference)
+   * @param valueType the value type (unused, for type inference)
+   * @return a new lockable dictionary
+   * @since 10.0.0
+   */
   public static <K, V> LockableRefToRefDictionary<K, V> stampedLockBasedRefToRefDictionary(
       Class<? super K> keyType,
       Class<? super V> valueType) {
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/HashEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/HashEntry.java
index 885f43f0..a27fad32 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/HashEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/HashEntry.java
@@ -1,5 +1,17 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An entry that stores its hash code for hash-based data structures.
+ *
+ * @since 10.0.0
+ */
 public interface HashEntry {
+
+  /**
+   * Returns the hash code of this entry.
+   *
+   * @return the hash code
+   * @since 10.0.0
+   */
   int hash();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefDictionary.java
index 71a6ea65..4a198619 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefDictionary.java
@@ -8,24 +8,74 @@
 import javasabr.rlib.functions.IntObjConsumer;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * A dictionary that maps int keys to reference values.
+ *
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface IntToRefDictionary<V> extends Dictionary<Integer, V> {
 
+  /**
+   * Creates a new entry with the specified key and value.
+   *
+   * @param <V> the type of the value
+   * @param key the key
+   * @param value the value
+   * @return a new entry
+   * @since 10.0.0
+   */
   static <V> IntToRefEntry<V> entry(int key, V value) {
     return new SimpleIntToRefEntry<>(key, value);
   }
 
+  /**
+   * Returns an empty immutable int-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @return an empty dictionary
+   * @since 10.0.0
+   */
   static <V> IntToRefDictionary<V> empty() {
     return ImmutableHashBasedIntToRefDictionary.empty();
   }
 
+  /**
+   * Creates an immutable dictionary with a single mapping.
+   *
+   * @param <V> the type of values
+   * @param key the key
+   * @param value the value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <V> IntToRefDictionary<V> of(int key, V value) {
     return ofEntries(entry(key, value));
   }
 
+  /**
+   * Creates an immutable dictionary with two mappings.
+   *
+   * @param <V> the type of values
+   * @param k1 the first key
+   * @param v1 the first value
+   * @param k2 the second key
+   * @param v2 the second value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <V> IntToRefDictionary<V> of(int k1, V v1, int k2, V v2) {
     return ofEntries(entry(k1, v1), entry(k2, v2));
   }
 
+  /**
+   * Creates an immutable dictionary from entries.
+   *
+   * @param <V> the type of values
+   * @param entries the entries
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <V> IntToRefDictionary<V> ofEntries(IntToRefEntry<V>... entries) {
     MutableIntToRefDictionary<V> mutable = DictionaryFactory.mutableIntToRefDictionary();
@@ -35,18 +85,66 @@ static <V> IntToRefDictionary<V> ofEntries(IntToRefEntry<V>... entries) {
     return mutable.toReadOnly();
   }
 
+  /**
+   * Returns whether this dictionary contains the specified key.
+   *
+   * @param key the key to check
+   * @return true if the key is present
+   * @since 10.0.0
+   */
   boolean containsKey(int key);
 
+  /**
+   * Returns the value for the specified key.
+   *
+   * @param key the key
+   * @return the value or null if not found
+   * @since 10.0.0
+   */
   @Nullable
   V get(int key);
 
+  /**
+   * Returns an optional containing the value for the specified key.
+   *
+   * @param key the key
+   * @return an optional with the value
+   * @since 10.0.0
+   */
   Optional<V> getOptional(int key);
 
+  /**
+   * Returns the value for the key, or a default value if not found.
+   *
+   * @param key the key
+   * @param def the default value
+   * @return the value or the default
+   * @since 10.0.0
+   */
   V getOrDefault(int key, V def);
 
+  /**
+   * Collects all keys into the provided mutable int array.
+   *
+   * @param container the array to add keys to
+   * @return the container with added keys
+   * @since 10.0.0
+   */
   MutableIntArray keys(MutableIntArray container);
 
+  /**
+   * Returns all keys as an immutable int array.
+   *
+   * @return an array of keys
+   * @since 10.0.0
+   */
   IntArray keys();
 
+  /**
+   * Performs the given action for each key-value pair.
+   *
+   * @param consumer the action to perform
+   * @since 10.0.0
+   */
   void forEach(IntObjConsumer<V> consumer);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefEntry.java
index 2aa7c172..6c3757a6 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/IntToRefEntry.java
@@ -1,7 +1,26 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An entry that maps an int key to a reference value.
+ *
+ * @param <V> the type of the value
+ * @since 10.0.0
+ */
 public interface IntToRefEntry<V> extends RefEntry<V> {
 
+  /**
+   * Returns the int key of this entry.
+   *
+   * @return the key
+   * @since 10.0.0
+   */
   int key();
+
+  /**
+   * Sets the int key of this entry.
+   *
+   * @param key the new key
+   * @since 10.0.0
+   */
   void key(int key);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedEntry.java
index c3312877..db9b32ab 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedEntry.java
@@ -2,8 +2,28 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An entry that maintains a link to the next entry in a chain.
+ *
+ * @param <N> the type of the next entry
+ * @since 10.0.0
+ */
 public interface LinkedEntry<N>  {
+
+  /**
+   * Returns the next entry in the chain.
+   *
+   * @return the next entry or null
+   * @since 10.0.0
+   */
   @Nullable
   N next();
+
+  /**
+   * Sets the next entry in the chain.
+   *
+   * @param next the next entry or null
+   * @since 10.0.0
+   */
   void next(@Nullable N next);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashEntry.java
index 7d472f8c..f3ab21b7 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashEntry.java
@@ -1,5 +1,13 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * A linked hash entry for reference-to-reference dictionaries.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @param <N> the type of the next entry
+ * @since 10.0.0
+ */
 public interface LinkedHashEntry<K, V, N extends LinkedHashEntry<K, V, N>>
     extends LinkedEntry<N>, HashEntry, RefToRefEntry<K, V> {
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashIntToRefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashIntToRefEntry.java
index a2b74e79..3980a27d 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashIntToRefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashIntToRefEntry.java
@@ -1,5 +1,12 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * A linked hash entry for int-to-reference dictionaries.
+ *
+ * @param <V> the type of values
+ * @param <N> the type of the next entry
+ * @since 10.0.0
+ */
 public interface LinkedHashIntToRefEntry<V, N extends LinkedHashIntToRefEntry<V, N>>
     extends LinkedEntry<N>, HashEntry, IntToRefEntry<V> {
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashLongToRefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashLongToRefEntry.java
index 21ad18db..4008447d 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashLongToRefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LinkedHashLongToRefEntry.java
@@ -1,5 +1,12 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * A linked hash entry for long-to-reference dictionaries.
+ *
+ * @param <V> the type of values
+ * @param <N> the type of the next entry
+ * @since 10.0.0
+ */
 public interface LinkedHashLongToRefEntry<V, N extends LinkedHashLongToRefEntry<V, N>>
     extends LinkedEntry<N>, HashEntry, LongToRefEntry<V> {
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LockableRefToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LockableRefToRefDictionary.java
index 07d16c71..5c1bda07 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LockableRefToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LockableRefToRefDictionary.java
@@ -4,8 +4,21 @@
 import javasabr.rlib.collections.operation.LockableSource;
 import javasabr.rlib.common.ThreadSafe;
 
+/**
+ * A thread-safe mutable dictionary that provides locking operations for concurrent access.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface LockableRefToRefDictionary<K, V> extends MutableRefToRefDictionary<K, V>,
     LockableSource, ThreadSafe {
 
+  /**
+   * Returns lockable operations for performing thread-safe operations on this dictionary.
+   *
+   * @return lockable operations
+   * @since 10.0.0
+   */
   LockableOperations<LockableRefToRefDictionary<K, V>> operations();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefDictionary.java
index bb1d7fd7..09964c0c 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefDictionary.java
@@ -8,24 +8,74 @@
 import javasabr.rlib.functions.LongObjConsumer;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * A dictionary that maps long keys to reference values.
+ *
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface LongToRefDictionary<V> extends Dictionary<Long, V> {
 
+  /**
+   * Creates a new entry with the specified key and value.
+   *
+   * @param <V> the type of the value
+   * @param key the key
+   * @param value the value
+   * @return a new entry
+   * @since 10.0.0
+   */
   static <V> LongToRefEntry<V> entry(long key, V value) {
     return new SimpleLongToRefEntry<>(key, value);
   }
 
+  /**
+   * Returns an empty immutable long-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @return an empty dictionary
+   * @since 10.0.0
+   */
   static <V> LongToRefDictionary<V> empty() {
     return ImmutableHashBasedLongToRefDictionary.empty();
   }
 
+  /**
+   * Creates an immutable dictionary with a single mapping.
+   *
+   * @param <V> the type of values
+   * @param key the key
+   * @param value the value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <V> LongToRefDictionary<V> of(long key, V value) {
     return ofEntries(entry(key, value));
   }
 
+  /**
+   * Creates an immutable dictionary with two mappings.
+   *
+   * @param <V> the type of values
+   * @param k1 the first key
+   * @param v1 the first value
+   * @param k2 the second key
+   * @param v2 the second value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <V> LongToRefDictionary<V> of(long k1, V v1, long k2, V v2) {
     return ofEntries(entry(k1, v1), entry(k2, v2));
   }
 
+  /**
+   * Creates an immutable dictionary from entries.
+   *
+   * @param <V> the type of values
+   * @param entries the entries
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <V> LongToRefDictionary<V> ofEntries(LongToRefEntry<V>... entries) {
     MutableLongToRefDictionary<V> mutable = DictionaryFactory.mutableLongToRefDictionary();
@@ -35,18 +85,66 @@ static <V> LongToRefDictionary<V> ofEntries(LongToRefEntry<V>... entries) {
     return mutable.toReadOnly();
   }
 
+  /**
+   * Returns whether this dictionary contains the specified key.
+   *
+   * @param key the key to check
+   * @return true if the key is present
+   * @since 10.0.0
+   */
   boolean containsKey(long key);
 
+  /**
+   * Returns the value for the specified key.
+   *
+   * @param key the key
+   * @return the value or null if not found
+   * @since 10.0.0
+   */
   @Nullable
   V get(long key);
 
+  /**
+   * Returns an optional containing the value for the specified key.
+   *
+   * @param key the key
+   * @return an optional with the value
+   * @since 10.0.0
+   */
   Optional<V> getOptional(long key);
 
+  /**
+   * Returns the value for the key, or a default value if not found.
+   *
+   * @param key the key
+   * @param def the default value
+   * @return the value or the default
+   * @since 10.0.0
+   */
   V getOrDefault(long key, V def);
 
+  /**
+   * Collects all keys into the provided mutable long array.
+   *
+   * @param container the array to add keys to
+   * @return the container with added keys
+   * @since 10.0.0
+   */
   MutableLongArray keys(MutableLongArray container);
 
+  /**
+   * Returns all keys as an immutable long array.
+   *
+   * @return an array of keys
+   * @since 10.0.0
+   */
   LongArray keys();
 
+  /**
+   * Performs the given action for each key-value pair.
+   *
+   * @param consumer the action to perform
+   * @since 10.0.0
+   */
   void forEach(LongObjConsumer<V> consumer);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefEntry.java
index 142feced..7cfbebb0 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/LongToRefEntry.java
@@ -1,6 +1,26 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An entry that maps a long key to a reference value.
+ *
+ * @param <V> the type of the value
+ * @since 10.0.0
+ */
 public interface LongToRefEntry<V> extends RefEntry<V> {
+
+  /**
+   * Returns the long key of this entry.
+   *
+   * @return the key
+   * @since 10.0.0
+   */
   long key();
+
+  /**
+   * Sets the long key of this entry.
+   *
+   * @param key the new key
+   * @since 10.0.0
+   */
   void key(long key);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableIntToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableIntToRefDictionary.java
index 6516ed43..da605f08 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableIntToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableIntToRefDictionary.java
@@ -7,56 +7,148 @@
 import javasabr.rlib.collections.dictionary.impl.DefaultMutableHashBasedIntToRefDictionary;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * A mutable dictionary that maps int keys to reference values.
+ *
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface MutableIntToRefDictionary<V> extends IntToRefDictionary<V> {
 
+  /**
+   * Creates a new mutable int-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @param valueType the value type (unused, for type inference)
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   static <V> MutableIntToRefDictionary<V> ofTypes(Class<V> valueType) {
     return new DefaultMutableHashBasedIntToRefDictionary<>();
   }
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(int key, Supplier<V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value from the key
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(int key, IntFunction<V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param <T> the type of the factory argument
+   * @param key the key
+   * @param arg1 the argument to pass to the factory
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   <T> V getOrCompute(int key, T arg1, Function<T, V> factory);
 
   /**
-   * @return the previous value for the key or null.
+   * Associates the value with the key.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V put(int key, V value);
 
   /**
-   * @return the existing value if the key is already present, or null if the key was absent and the new mapping was added.
+   * Associates the value with the key if not already present.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the existing value if present, or null if added
+   * @since 10.0.0
    */
   @Nullable
   V putIfAbsent(int key, V value);
-  
+
+  /**
+   * Copies all mappings from the specified dictionary.
+   *
+   * @param dictionary the dictionary to copy from
+   * @since 10.0.0
+   */
   void putAll(IntToRefDictionary<? extends V> dictionary);
 
+  /**
+   * Copies all mappings from the specified dictionary and returns this.
+   *
+   * @param dictionary the dictionary to copy from
+   * @return this dictionary
+   * @since 10.0.0
+   */
   MutableIntToRefDictionary<V> append(IntToRefDictionary<? extends V> dictionary);
 
   /**
-   * @return the optional value of the previous value for the key.
+   * Associates the value with the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @param value the value
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> putOptional(int key, V value);
 
   /**
-   * @return the previous value for the key or null.
+   * Removes the mapping for the key.
+   *
+   * @param key the key
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V remove(int key);
 
   /**
-   * @return true if the expectedValue was removed
+   * Removes the mapping for the key only if it maps to the expected value.
+   *
+   * @param key the key
+   * @param expectedValue the expected value
+   * @return true if the expected value was removed
+   * @since 10.0.0
    */
   boolean remove(int key, V expectedValue);
-  
+
   /**
-   * @return the optional value of the previous value for the key.
+   * Removes the mapping for the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> removeOptional(int key);
 
+  /**
+   * Removes all mappings from this dictionary.
+   *
+   * @since 10.0.0
+   */
   void clear();
 
+  /**
+   * Returns an immutable copy of this dictionary.
+   *
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   IntToRefDictionary<V> toReadOnly();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableLongToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableLongToRefDictionary.java
index 15866783..ecb973be 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableLongToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableLongToRefDictionary.java
@@ -7,56 +7,148 @@
 import javasabr.rlib.collections.dictionary.impl.DefaultMutableHashBasedLongToRefDictionary;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * A mutable dictionary that maps long keys to reference values.
+ *
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface MutableLongToRefDictionary<V> extends LongToRefDictionary<V> {
 
+  /**
+   * Creates a new mutable long-to-reference dictionary.
+   *
+   * @param <V> the type of values
+   * @param valueType the value type (unused, for type inference)
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   static <V> MutableLongToRefDictionary<V> ofTypes(Class<V> valueType) {
     return new DefaultMutableHashBasedLongToRefDictionary<>();
   }
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(long key, Supplier<V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value from the key
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(long key, LongFunction<V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param <T> the type of the factory argument
+   * @param key the key
+   * @param arg1 the argument to pass to the factory
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   <T> V getOrCompute(long key, T arg1, Function<T, V> factory);
 
   /**
-   * @return the previous value for the key or null.
+   * Associates the value with the key.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V put(long key, V value);
 
   /**
-   * @return the existing value if the key is already present, or null if the key was absent and the new mapping was added.
+   * Associates the value with the key if not already present.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the existing value if present, or null if added
+   * @since 10.0.0
    */
   @Nullable
   V putIfAbsent(long key, V value);
-  
+
+  /**
+   * Copies all mappings from the specified dictionary.
+   *
+   * @param dictionary the dictionary to copy from
+   * @since 10.0.0
+   */
   void putAll(LongToRefDictionary<? extends V> dictionary);
 
+  /**
+   * Copies all mappings from the specified dictionary and returns this.
+   *
+   * @param dictionary the dictionary to copy from
+   * @return this dictionary
+   * @since 10.0.0
+   */
   MutableLongToRefDictionary<V> append(LongToRefDictionary<? extends V> dictionary);
 
   /**
-   * @return the optional value of the previous value for the key.
+   * Associates the value with the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @param value the value
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> putOptional(long key, V value);
 
   /**
-   * @return the previous value for the key or null.
+   * Removes the mapping for the key.
+   *
+   * @param key the key
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V remove(long key);
 
   /**
-   * @return true if the expectedValue was removed
+   * Removes the mapping for the key only if it maps to the expected value.
+   *
+   * @param key the key
+   * @param expectedValue the expected value
+   * @return true if the expected value was removed
+   * @since 10.0.0
    */
   boolean remove(long key, V expectedValue);
-  
+
   /**
-   * @return the optional value of the previous value for the key.
+   * Removes the mapping for the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> removeOptional(long key);
 
+  /**
+   * Removes all mappings from this dictionary.
+   *
+   * @since 10.0.0
+   */
   void clear();
 
+  /**
+   * Returns an immutable copy of this dictionary.
+   *
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   LongToRefDictionary<V> toReadOnly();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableRefToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableRefToRefDictionary.java
index ff3f1437..bf017599 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableRefToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/MutableRefToRefDictionary.java
@@ -6,58 +6,153 @@
 import javasabr.rlib.collections.dictionary.impl.DefaultMutableHashBasedRefToRefDictionary;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * A mutable dictionary that maps reference keys to reference values.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface MutableRefToRefDictionary<K, V> extends RefToRefDictionary<K, V> {
 
+  /**
+   * Creates a new mutable reference-to-reference dictionary.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param keyType the key type (unused, for type inference)
+   * @param valueType the value type (unused, for type inference)
+   * @return a new mutable dictionary
+   * @since 10.0.0
+   */
   static <K, V> MutableRefToRefDictionary<K, V> ofTypes(
       Class<K> keyType,
       Class<V> valueType) {
     return new DefaultMutableHashBasedRefToRefDictionary<>();
   }
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(K key, Supplier<V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param key the key
+   * @param factory the factory to compute the value from the key
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   V getOrCompute(K key, Function<K, V> factory);
 
+  /**
+   * Returns the value for the key, computing it if absent.
+   *
+   * @param <T> the type of the factory argument
+   * @param key the key
+   * @param arg1 the argument to pass to the factory
+   * @param factory the factory to compute the value
+   * @return the existing or computed value
+   * @since 10.0.0
+   */
   <T> V getOrCompute(K key, T arg1, Function<T, V> factory);
 
   /**
-   * @return the previous value for the key or null.
+   * Associates the value with the key.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V put(K key, V value);
 
   /**
-   * @return the existing value if the key is already present, or null if the key was absent and the new mapping was added.
+   * Associates the value with the key if not already present.
+   *
+   * @param key the key
+   * @param value the value
+   * @return the existing value if present, or null if added
+   * @since 10.0.0
    */
   @Nullable 
   V putIfAbsent(K key, V value);
-  
+
+  /**
+   * Copies all mappings from the specified dictionary.
+   *
+   * @param dictionary the dictionary to copy from
+   * @since 10.0.0
+   */
   void putAll(RefToRefDictionary<? extends K, ? extends V> dictionary);
 
+  /**
+   * Copies all mappings from the specified dictionary and returns this.
+   *
+   * @param dictionary the dictionary to copy from
+   * @return this dictionary
+   * @since 10.0.0
+   */
   MutableRefToRefDictionary<K, V> append(RefToRefDictionary<? extends K, ? extends V> dictionary);
 
   /**
-   * @return the optional value of the previous value for the key.
+   * Associates the value with the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @param value the value
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> putOptional(K key, V value);
 
   /**
-   * @return the previous value for the key or null.
+   * Removes the mapping for the key.
+   *
+   * @param key the key
+   * @return the previous value for the key or null
+   * @since 10.0.0
    */
   @Nullable
   V remove(K key);
 
   /**
-   * @return true if the expectedValue was removed
+   * Removes the mapping for the key only if it maps to the expected value.
+   *
+   * @param key the key
+   * @param expectedValue the expected value
+   * @return true if the expected value was removed
+   * @since 10.0.0
    */
   boolean remove(K key, V expectedValue);
-  
+
   /**
-   * @return the optional value of the previous value for the key.
+   * Removes the mapping for the key and returns an optional of the previous value.
+   *
+   * @param key the key
+   * @return an optional of the previous value
+   * @since 10.0.0
    */
   Optional<V> removeOptional(K key);
 
+  /**
+   * Removes all mappings from this dictionary.
+   *
+   * @since 10.0.0
+   */
   void clear();
 
+  /**
+   * Returns an immutable copy of this dictionary.
+   *
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   RefToRefDictionary<K, V> toReadOnly();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefEntry.java
index dd2f75b0..f9b14316 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefEntry.java
@@ -2,7 +2,27 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An entry that holds a reference value.
+ *
+ * @param <V> the type of the value
+ * @since 10.0.0
+ */
 public interface RefEntry<V> {
+
+  /**
+   * Returns the value of this entry.
+   *
+   * @return the value or null
+   * @since 10.0.0
+   */
   @Nullable V value();
+
+  /**
+   * Sets the value of this entry.
+   *
+   * @param value the new value or null
+   * @since 10.0.0
+   */
   void value(@Nullable V value);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionary.java
index cb489e04..5c80f614 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionary.java
@@ -4,47 +4,161 @@
 import javasabr.rlib.collections.dictionary.impl.ImmutableHashBasedRefToRefDictionary;
 import javasabr.rlib.collections.dictionary.impl.SimpleRefToRefEntry;
 
+/**
+ * A dictionary that maps reference keys to reference values.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 public interface RefToRefDictionary<K, V> extends Dictionary<K, V> {
 
+  /**
+   * Creates a new builder for constructing an immutable dictionary.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @return a new builder
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionaryBuilder<K, V> builder() {
     return new RefToRefDictionaryBuilder<>();
   }
 
+  /**
+   * Creates a new builder for constructing an immutable dictionary with explicit types.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param keyType the key type (unused, for type inference)
+   * @param valueType the value type (unused, for type inference)
+   * @return a new builder
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionaryBuilder<K, V> builder(
       Class<? super K> keyType, 
       Class<? super V> valueType) {
     return new RefToRefDictionaryBuilder<>();
   }
 
+  /**
+   * Creates a builder and adds the first key-value pair.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param key the first key
+   * @param value the first value
+   * @return a builder with the entry added
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionaryBuilder<K, V> startWith(K key, V value) {
     return new RefToRefDictionaryBuilder<K, V>()
         .put(key, value);
   }
-  
+
+  /**
+   * Creates a new entry with the specified key and value.
+   *
+   * @param <K> the type of the key
+   * @param <V> the type of the value
+   * @param key the key
+   * @param value the value
+   * @return a new entry
+   * @since 10.0.0
+   */
   static <K, V> RefToRefEntry<K, V> entry(K key, V value) {
     return new SimpleRefToRefEntry<>(key, value);
   }
 
+  /**
+   * Returns an empty immutable reference-to-reference dictionary.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @return an empty dictionary
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionary<K, V> empty() {
     return ImmutableHashBasedRefToRefDictionary.empty();
   }
 
+  /**
+   * Creates an immutable dictionary with a single mapping.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param key the key
+   * @param value the value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionary<K, V> of(K key, V value) {
     return ofEntries(entry(key, value));
   }
 
+  /**
+   * Creates an immutable dictionary with two mappings.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param k1 the first key
+   * @param v1 the first value
+   * @param k2 the second key
+   * @param v2 the second value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionary<K, V> of(K k1, V v1, K k2, V v2) {
     return ofEntries(entry(k1, v1), entry(k2, v2));
   }
 
+  /**
+   * Creates an immutable dictionary with three mappings.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param k1 the first key
+   * @param v1 the first value
+   * @param k2 the second key
+   * @param v2 the second value
+   * @param k3 the third key
+   * @param v3 the third value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionary<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) {
     return ofEntries(entry(k1, v1), entry(k2, v2), entry(k3, v3));
   }
 
+  /**
+   * Creates an immutable dictionary with four mappings.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param k1 the first key
+   * @param v1 the first value
+   * @param k2 the second key
+   * @param v2 the second value
+   * @param k3 the third key
+   * @param v3 the third value
+   * @param k4 the fourth key
+   * @param v4 the fourth value
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   static <K, V> RefToRefDictionary<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
     return ofEntries(entry(k1, v1), entry(k2, v2), entry(k3, v3), entry(k4, v4));
   }
 
+  /**
+   * Creates an immutable dictionary from entries.
+   *
+   * @param <K> the type of keys
+   * @param <V> the type of values
+   * @param entries the entries
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   @SafeVarargs
   static <K, V> RefToRefDictionary<K, V> ofEntries(RefToRefEntry<K, V>... entries) {
     MutableRefToRefDictionary<K, V> mutable = DictionaryFactory.mutableRefToRefDictionary();
@@ -54,5 +168,11 @@ static <K, V> RefToRefDictionary<K, V> ofEntries(RefToRefEntry<K, V>... entries)
     return mutable.toReadOnly();
   }
 
+  /**
+   * Performs the given action for each key-value pair.
+   *
+   * @param consumer the action to perform
+   * @since 10.0.0
+   */
   void forEach(BiConsumer<K, V> consumer);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionaryBuilder.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionaryBuilder.java
index 2c269c67..769b8d94 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionaryBuilder.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefDictionaryBuilder.java
@@ -4,32 +4,72 @@
 import lombok.AccessLevel;
 import lombok.experimental.FieldDefaults;
 
+/**
+ * A builder for constructing immutable {@link RefToRefDictionary} instances.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @since 10.0.0
+ */
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
 public class RefToRefDictionaryBuilder<K, V> {
   
   MutableRefToRefDictionary<K, V> elements;
 
+  /**
+   * Creates a new dictionary builder.
+   *
+   * @since 10.0.0
+   */
   public RefToRefDictionaryBuilder() {
     this.elements = DictionaryFactory.mutableRefToRefDictionary();
   }
-  
+
+  /**
+   * Adds a key-value mapping to the dictionary being built.
+   *
+   * @param key the key
+   * @param value the value
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public RefToRefDictionaryBuilder<K, V> put(K key, V value) {
     this.elements.put(key, value);
     return this;
   }
 
+  /**
+   * Adds all mappings from another dictionary to the dictionary being built.
+   *
+   * @param other the dictionary to add mappings from
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public RefToRefDictionaryBuilder<K, V> put(RefToRefDictionary<K, V> other) {
     this.elements.putAll(other);
     return this;
   }
 
+  /**
+   * Adds all mappings from a map to the dictionary being built.
+   *
+   * @param other the map to add mappings from
+   * @return this builder for method chaining
+   * @since 10.0.0
+   */
   public RefToRefDictionaryBuilder<K, V> put(Map<K, V> other) {
     for (Map.Entry<K, V> entry : other.entrySet()) {
       elements.put(entry.getKey(), entry.getValue());
     }
     return this;
   }
-  
+
+  /**
+   * Builds and returns an immutable dictionary containing all added mappings.
+   *
+   * @return an immutable dictionary
+   * @since 10.0.0
+   */
   public RefToRefDictionary<K, V> build() {
     return elements.toReadOnly();
   }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefEntry.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefEntry.java
index ea14f74e..8f91b47d 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefEntry.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/RefToRefEntry.java
@@ -1,6 +1,27 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An entry that maps a reference key to a reference value.
+ *
+ * @param <K> the type of the key
+ * @param <V> the type of the value
+ * @since 10.0.0
+ */
 public interface RefToRefEntry<K, V> extends RefEntry<V> {
+
+  /**
+   * Returns the key of this entry.
+   *
+   * @return the key
+   * @since 10.0.0
+   */
   K key();
+
+  /**
+   * Sets the key of this entry.
+   *
+   * @param key the new key
+   * @since 10.0.0
+   */
   void key(K key);
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeIntToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeIntToRefDictionary.java
index b80b63e9..dfcdd5ec 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeIntToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeIntToRefDictionary.java
@@ -2,7 +2,20 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An unsafe view of an int-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeIntToRefDictionary<V, E extends IntToRefEntry<V>> extends IntToRefDictionary<V> {
 
+  /**
+   * Returns the internal entry array.
+   *
+   * @return the entry array or null
+   * @since 10.0.0
+   */
   @Nullable E[] entries();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeLongToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeLongToRefDictionary.java
index bd52c2c3..e3bdec6f 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeLongToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeLongToRefDictionary.java
@@ -2,7 +2,20 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An unsafe view of a long-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeLongToRefDictionary<V, E extends LongToRefEntry<V>> extends LongToRefDictionary<V> {
 
+  /**
+   * Returns the internal entry array.
+   *
+   * @return the entry array or null
+   * @since 10.0.0
+   */
   @Nullable E[] entries();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableIntToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableIntToRefDictionary.java
index 6a1fecb8..33465829 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableIntToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableIntToRefDictionary.java
@@ -1,5 +1,12 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An unsafe mutable view of an int-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeMutableIntToRefDictionary<V, E extends IntToRefEntry<V>>
     extends MutableIntToRefDictionary<V>, UnsafeIntToRefDictionary<V, E> {
 
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableLongToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableLongToRefDictionary.java
index 1ed37350..a901881e 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableLongToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableLongToRefDictionary.java
@@ -1,5 +1,12 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An unsafe mutable view of a long-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeMutableLongToRefDictionary<V, E extends LongToRefEntry<V>>
     extends MutableLongToRefDictionary<V>, UnsafeLongToRefDictionary<V, E> {
 
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableRefToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableRefToRefDictionary.java
index c4c98de2..7f69eac5 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableRefToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeMutableRefToRefDictionary.java
@@ -1,5 +1,13 @@
 package javasabr.rlib.collections.dictionary;
 
+/**
+ * An unsafe mutable view of a reference-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeMutableRefToRefDictionary<K, V, E extends RefToRefEntry<K, V>>
     extends MutableRefToRefDictionary<K, V>, UnsafeRefToRefDictionary<K, V, E> {
 
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeRefToRefDictionary.java b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeRefToRefDictionary.java
index 97e8bca9..a7834d02 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeRefToRefDictionary.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/dictionary/UnsafeRefToRefDictionary.java
@@ -2,8 +2,22 @@
 
 import org.jspecify.annotations.Nullable;
 
+/**
+ * An unsafe view of a reference-to-reference dictionary providing direct access to internal entries.
+ *
+ * @param <K> the type of keys
+ * @param <V> the type of values
+ * @param <E> the type of entries
+ * @since 10.0.0
+ */
 public interface UnsafeRefToRefDictionary<K, V, E extends RefToRefEntry<K, V>>
     extends RefToRefDictionary<K, V> {
 
+  /**
+   * Returns the internal entry array.
+   *
+   * @return the entry array or null
+   * @since 10.0.0
+   */
   @Nullable E[] entries();
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableOperations.java b/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableOperations.java
index ea1b74f1..1733bb1a 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableOperations.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableOperations.java
@@ -9,28 +9,136 @@
 import javasabr.rlib.functions.TriConsumer;
 import javasabr.rlib.functions.TriFunction;
 
+/**
+ * Provides thread-safe operations on a lockable source with automatic lock management.
+ *
+ * @param <S> the type of the lockable source
+ * @since 10.0.0
+ */
 public interface LockableOperations<S extends LockableSource> {
 
+  /**
+   * Executes a function within a read lock and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R> R getInReadLock(Function<S, R> function);
 
+  /**
+   * Executes a function within a read lock with one argument and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param <A> the type of the argument
+   * @param arg1 the argument
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R, A> R getInReadLock(A arg1, BiFunction<S, A, R> function);
 
+  /**
+   * Executes a function within a read lock with an int argument and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param arg1 the int argument
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R> R getInReadLock(int arg1, ObjIntFunction<S, R> function);
 
+  /**
+   * Executes a function within a read lock with two arguments and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param <A> the type of the first argument
+   * @param <B> the type of the second argument
+   * @param arg1 the first argument
+   * @param arg2 the second argument
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R, A, B> R getInReadLock(A arg1, B arg2, TriFunction<S, A, B, R> function);
 
+  /**
+   * Executes a boolean function within a read lock with one argument.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument
+   * @param function the function to execute
+   * @return the boolean result
+   * @since 10.0.0
+   */
   <A> boolean getBooleanInReadLock(A arg1, BiObjToBooleanFunction<S, A> function);
 
+  /**
+   * Executes a consumer within a read lock with one argument.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument
+   * @param function the consumer to execute
+   * @since 10.0.0
+   */
   <A> void inReadLock(A arg1, BiConsumer<S, A> function);
 
+  /**
+   * Executes a function within a write lock with one argument and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param <A> the type of the argument
+   * @param arg1 the argument
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R, A> R getInWriteLock(A arg1, BiFunction<S, A, R> function);
 
+  /**
+   * Executes a function within a write lock with two arguments and returns the result.
+   *
+   * @param <R> the type of the result
+   * @param <A> the type of the first argument
+   * @param <B> the type of the second argument
+   * @param arg1 the first argument
+   * @param arg2 the second argument
+   * @param function the function to execute
+   * @return the result of the function
+   * @since 10.0.0
+   */
   <R, A, B> R getInWriteLock(A arg1, B arg2, TriFunction<S, A, B, R> function);
 
+  /**
+   * Executes a consumer within a write lock.
+   *
+   * @param function the consumer to execute
+   * @since 10.0.0
+   */
   void inWriteLock(Consumer<S> function);
 
+  /**
+   * Executes a consumer within a write lock with one argument.
+   *
+   * @param <A> the type of the argument
+   * @param arg1 the argument
+   * @param function the consumer to execute
+   * @since 10.0.0
+   */
   <A> void inWriteLock(A arg1, BiConsumer<S, A> function);
 
+  /**
+   * Executes a consumer within a write lock with two arguments.
+   *
+   * @param <A> the type of the first argument
+   * @param <B> the type of the second argument
+   * @param arg1 the first argument
+   * @param arg2 the second argument
+   * @param function the consumer to execute
+   * @since 10.0.0
+   */
   <A, B> void inWriteLock(A arg1, B arg2, TriConsumer<S, A, B> function);
 
 }
diff --git a/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableSource.java b/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableSource.java
index 0d4eb78d..9b01486b 100644
--- a/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableSource.java
+++ b/rlib-collections/src/main/java/javasabr/rlib/collections/operation/LockableSource.java
@@ -1,13 +1,58 @@
 package javasabr.rlib.collections.operation;
 
+/**
+ * A source that provides locking primitives for thread-safe access.
+ *
+ * @since 10.0.0
+ */
 public interface LockableSource {
 
+  /**
+   * Acquires a read lock and returns a stamp for later unlock.
+   *
+   * @return a stamp representing the acquired lock
+   * @since 10.0.0
+   */
   long readLock();
+
+  /**
+   * Releases a read lock using the provided stamp.
+   *
+   * @param stamp the stamp from readLock()
+   * @since 10.0.0
+   */
   void readUnlock(long stamp);
+
+  /**
+   * Attempts an optimistic read, returning a stamp for validation.
+   *
+   * @return a stamp for validation
+   * @since 10.0.0
+   */
   long tryOptimisticRead();
 
+  /**
+   * Validates that a lock stamp is still valid.
+   *
+   * @param stamp the stamp to validate
+   * @return true if the stamp is still valid
+   * @since 10.0.0
+   */
   boolean validateLock(long stamp);
 
+  /**
+   * Acquires a write lock and returns a stamp for later unlock.
+   *
+   * @return a stamp representing the acquired lock
+   * @since 10.0.0
+   */
   long writeLock();
+
+  /**
+   * Releases a write lock using the provided stamp.
+   *
+   * @param stamp the stamp from writeLock()
+   * @since 10.0.0
+   */
   void writeUnlock(long stamp);
 }