Add documentations for public api

Author: Abduqodiri Qurbonzoda

kotlinx-collections-immutable/src/main/kotlin/kotlinx/collections/immutable/ImmutableCollection.kt

@@ -16,24 +16,106 @@
 
 package kotlinx.collections.immutable
 
+/**
+ * A generic immutable collection of elements. Methods in this interface support only read-only access to the collection.
+ *
+ * Modification operations are supported through the [PersistentCollection] interface.
+ *
+ * Implementors of this interface take responsibility to be immutable.
+ * Once constructed they must contain the same elements in the same order.
+ *
+ * @param E the type of elements contained in the collection. The immutable collection is covariant on its element type.
+ */
 public interface ImmutableCollection<out E>: Collection<E>
 
+/**
+ * A generic persistent collection of elements that supports adding and removing elements.
+ *
+ * Modification operations return new instances of the persistent collection with the modification applied.
+ *
+ * @param E the type of elements contained in the collection. The persistent collection is covariant on its element type.
+ */
 public interface PersistentCollection<out E> : ImmutableCollection<E> {
+    /**
+     * Returns the result of adding the specified [element] to this collection.
+     *
+     * @returns a new persistent collection with the specified [element] added;
+     * or this instance if this collection does not support duplicates and it already contains the element.
+     */
     fun add(element: @UnsafeVariance E): PersistentCollection<E>
 
+    /**
+     * Returns the result of adding all elements of the specified [elements] collection to this collection.
+     *
+     * @return a new persistent collection with elements of the specified [elements] collection added;
+     * or this instance if no modifications were made in the result of this operation.
+     */
     fun addAll(elements: Collection<@UnsafeVariance E>): PersistentCollection<E>
 
+    /**
+     * Returns the result of removing a single appearance of the specified [element] from this collection.
+     *
+     * @return a new persistent collection with a single appearance of the specified [element] removed;
+     * or this instance if there is no such element in this collection.
+     */
     fun remove(element: @UnsafeVariance E): PersistentCollection<E>
 
+    /**
+     * Returns the result of removing all elements in this collection that are also
+     * contained in the specified [elements] collection.
+     *
+     * @return a new persistent collection with elements in this collection that are also
+     * contained in the specified [elements] collection removed;
+     * or this instance if no modifications were made in the result of this operation.
+     */
     fun removeAll(elements: Collection<@UnsafeVariance E>): PersistentCollection<E>
 
+    /**
+     * Returns the result of removing all elements in this collection that match the specified [predicate].
+     *
+     * @return a new persistent collection with elements matching the specified [predicate] removed;
+     * or this instance if no elements match the predicate.
+     */
     fun removeAll(predicate: (E) -> Boolean): PersistentCollection<E>
 
+    /**
+     * Returns an empty persistent collection.
+     */
     fun clear(): PersistentCollection<E>
 
+    /**
+     * A generic builder of the persistent collection. Builder exposes its modification operations through the [MutableCollection] interface.
+     *
+     * Builders are reusable, that is [build] method can be called multiple times with modifications between these calls.
+     * However, modifications applied do not affect previously built persistent collection instances.
+     *
+     * Builder is backed by the same underlying data structure as the persistent collection it was created from.
+     * Thus, [builder] and [build] methods take constant time consisting of passing the backing storage to the
+     * new builder and persistent collection instances, respectively.
+     *
+     * The builder tracks which nodes in the structure are shared with the persistent collection,
+     * and which are owned by it exclusively. It owns the nodes it copied during modification
+     * operations and avoids copying them on subsequent modifications.
+     *
+     * When [build] is called the builder forgets about all owned nodes it had created.
+     */
     interface Builder<E>: MutableCollection<E> {
+        /**
+         * Returns a persistent collection with the same contents as this builder.
+         *
+         * This method can be called multiple times.
+         *
+         * If operations applied on this builder have caused no modifications:
+         * - on the first call it returns the same persistent collection instance this builder was obtained from.
+         * - on subsequent calls it returns the same previously returned persistent collection instance.
+         */
         fun build(): PersistentCollection<E>
     }
 
+    /**
+     * Returns a new builder with the same contents as this collection.
+     *
+     * The builder can be used to efficiently perform multiple modification operations.
+     */
     fun builder(): Builder<@UnsafeVariance E>
-}
+}

kotlinx-collections-immutable/src/main/kotlin/kotlinx/collections/immutable/ImmutableList.kt

@@ -18,11 +18,29 @@ package kotlinx.collections.immutable
 
 import kotlinx.collections.immutable.internal.ListImplementation
 
+/**
+ * A generic immutable ordered collection of elements. Methods in this interface support only read-only access to the immutable list.
+ *
+ * Modification operations are supported through the [PersistentList] interface.
+ *
+ * Implementors of this interface take responsibility to be immutable.
+ * Once constructed they must contain the same elements in the same order.
+ *
+ * @param E the type of elements contained in the list. The immutable list is covariant on its element type.
+ */
 public interface ImmutableList<out E> : List<E>, ImmutableCollection<E> {
 
+    /**
+     * Returns a view of the portion of this list between the specified [fromIndex] (inclusive) and [toIndex] (exclusive).
+     *
+     * The returned list is backed by this list.
+     *
+     * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this list.
+     * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex].
+     */
     override fun subList(fromIndex: Int, toIndex: Int): ImmutableList<E> = SubList(this, fromIndex, toIndex)
 
-    public class SubList<E>(private val source: ImmutableList<E>, private val fromIndex: Int, private val toIndex: Int) : ImmutableList<E>, AbstractList<E>() {
+    private class SubList<E>(private val source: ImmutableList<E>, private val fromIndex: Int, private val toIndex: Int) : ImmutableList<E>, AbstractList<E>() {
         private var _size: Int = 0
 
         init {
@@ -42,35 +60,111 @@ public interface ImmutableList<out E> : List<E>, ImmutableCollection<E> {
             ListImplementation.checkRangeIndexes(fromIndex, toIndex, this._size)
             return SubList(source, this.fromIndex + fromIndex, this.fromIndex + toIndex)
         }
-
     }
 }
 
+/**
+ * A generic persistent ordered collection of elements that supports adding and removing elements.
+ *
+ * Modification operations return new instances of the persistent list with the modification applied.
+ *
+ * @param E the type of elements contained in the list. The persistent list is covariant on its element type.
+ */
 public interface PersistentList<out E> : ImmutableList<E>, PersistentCollection<E> {
+    /**
+     * Returns a new persistent list with the specified [element] appended.
+     */
     override fun add(element: @UnsafeVariance E): PersistentList<E>
 
+    /**
+     * Returns the result of appending all elements of the specified [elements] collection to this list.
+     *
+     * The elements are appended in the order they appear in the specified collection.
+     *
+     * @return a new persistent list with elements of the specified [elements] collection appended;
+     * or this instance if the specified collection is empty.
+     */
     override fun addAll(elements: Collection<@UnsafeVariance E>): PersistentList<E> // = super<ImmutableCollection>.addAll(elements) as ImmutableList
 
+    /**
+     * Returns the result of removing the first appearance of the specified [element] from this list.
+     *
+     * @return a new persistent list with the first appearance of the specified [element] removed;
+     * or this instance if there is no such element in this list.
+     */
     override fun remove(element: @UnsafeVariance E): PersistentList<E>
 
+    /**
+     * Returns the result of removing all elements in this list that are also
+     * contained in the specified [elements] collection.
+     *
+     * @return a new persistent list with elements in this list that are also
+     * contained in the specified [elements] collection removed;
+     * or this instance if no modifications were made in the result of this operation.
+     */
     override fun removeAll(elements: Collection<@UnsafeVariance E>): PersistentList<E>
 
+    /**
+     * Returns the result of removing all elements in this list that match the specified [predicate].
+     *
+     * @return a new persistent list with elements matching the specified [predicate] removed;
+     * or this instance if no elements match the predicate.
+     */
     override fun removeAll(predicate: (E) -> Boolean): PersistentList<E>
 
+    /**
+     * Returns an empty persistent list.
+     */
     override fun clear(): PersistentList<E>
 
 
+    /**
+     * Returns the result of inserting the specified [c] collection at the specified [index].
+     *
+     * @return a new persistent list with the specified [c] collection inserted at the specified [index];
+     * or this instance if the specified collection is empty.
+     *
+     * @throws IndexOutOfBoundsException if [index] is out of bounds of this list.
+     */
     fun addAll(index: Int, c: Collection<@UnsafeVariance E>): PersistentList<E> // = builder().apply { addAll(index, c.toList()) }.build()
 
+    /**
+     * Returns a new persistent list with the element at the specified [index] replaced with the specified [element].
+     *
+     * @throws IndexOutOfBoundsException if [index] is out of bounds of this list.
+     */
     fun set(index: Int, element: @UnsafeVariance E): PersistentList<E>
 
     /**
-     * Inserts an element into the list at the specified [index].
+     * Returns a new persistent list with the specified [element] inserted at the specified [index].
+     *
+     * @throws IndexOutOfBoundsException if [index] is out of bounds of this list.
      */
     fun add(index: Int, element: @UnsafeVariance E): PersistentList<E>
 
+    /**
+     * Returns a new persistent list with the element at the specified [index] removed.
+     *
+     * @throws IndexOutOfBoundsException if [index] is out of bounds of this list.
+     */
     fun removeAt(index: Int): PersistentList<E>
 
+    /**
+     * A generic builder of the persistent list. Builder exposes its modification operations through the [MutableList] interface.
+     *
+     * Builders are reusable, that is [build] method can be called multiple times with modifications between these calls.
+     * However, modifications applied do not affect previously built persistent list instances.
+     *
+     * Builder is backed by the same underlying data structure as the persistent list it was created from.
+     * Thus, [builder] and [build] methods take constant time consisting of passing the backing storage to the
+     * new builder and persistent list instances, respectively.
+     *
+     * The builder tracks which nodes in the structure are shared with the persistent list,
+     * and which are owned by it exclusively. It owns the nodes it copied during modification
+     * operations and avoids copying them on subsequent modifications.
+     *
+     * When [build] is called the builder forgets about all owned nodes it had created.
+     */
     interface Builder<E>: MutableList<E>, PersistentCollection.Builder<E> {
         override fun build(): PersistentList<E>
     }

kotlinx-collections-immutable/src/main/kotlin/kotlinx/collections/immutable/ImmutableMap.kt

@@ -16,7 +16,20 @@
 
 package kotlinx.collections.immutable
 
-
+/**
+ * A generic immutable collection that holds pairs of objects (keys and values) and supports efficiently retrieving
+ * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
+ * Methods in this interface support only read-only access to the immutable map.
+ *
+ * Modification operations are supported through the [PersistentMap] interface.
+ *
+ * Implementors of this interface take responsibility to be immutable.
+ * Once constructed they must contain the same elements in the same order.
+ *
+ * @param K the type of map keys. The map is invariant on its key type, as it
+ *          can accept key as a parameter (of [containsKey] for example) and return it in [keys] set.
+ * @param V the type of map values. The map is covariant on its value type.
+ */
 public interface ImmutableMap<K, out V>: Map<K, V> {
 
     override val keys: ImmutableSet<K>
@@ -27,21 +40,91 @@ public interface ImmutableMap<K, out V>: Map<K, V> {
 }
 
 
-
+/**
+ * A generic persistent collection that holds pairs of objects (keys and values) and supports efficiently retrieving
+ * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
+ *
+ * Modification operations return new instances of the persistent map with the modification applied.
+ *
+ * @param K the type of map keys. The map is invariant on its key type.
+ * @param V the type of map values. The persistent map is covariant on its value type.
+ */
 public interface PersistentMap<K, out V> : ImmutableMap<K, V> {
+    /**
+     * Returns the result of associating the specified [value] with the specified [key] in this map.
+     *
+     * If this map already contains a mapping for the key, the old value is replaced by the specified value.
+     *
+     * @return a new persistent map with the specified [value] associated with the specified [key];
+     * or this instance if no modifications were made in the result of this operation.
+     */
     fun put(key: K, value: @UnsafeVariance V): PersistentMap<K, V>
 
+    /**
+     * Returns the result of removing the specified [key] and its corresponding value from this map.
+     *
+     * @return a new persistent map with the specified [key] and its corresponding value removed;
+     * or this instance if it contains no mapping for the key.
+     */
     fun remove(key: K): PersistentMap<K, V>
 
+    /**
+     * Returns the result of removing the entry that maps the specified [key] to the specified [value].
+     *
+     * @return a new persistent map with the entry for the specified [key] and [value] removed;
+     * or this instance if it contains no entry with the specified key and value.
+     */
     fun remove(key: K, value: @UnsafeVariance V): PersistentMap<K, V>
 
+    /**
+     * Returns the result of merging the specified [m] map with this map.
+     *
+     * The effect of this call is equivalent to that of calling `put(k, v)` once for each
+     * mapping from key `k` to value `v` in the specified map.
+     *
+     * @return a new persistent map with keys and values from the specified map [m] associated;
+     * or this instance if no modifications were made in the result of this operation.
+     */
     fun putAll(m: Map<out K, @UnsafeVariance V>): PersistentMap<K, V>  // m: Iterable<Map.Entry<K, V>> or Map<out K,V> or Iterable<Pair<K, V>>
 
+    /**
+     * Returns an empty persistent map.
+     */
     fun clear(): PersistentMap<K, V>
 
+    /**
+     * A generic builder of the persistent map. Builder exposes its modification operations through the [MutableMap] interface.
+     *
+     * Builders are reusable, that is [build] method can be called multiple times with modifications between these calls.
+     * However, modifications applied do not affect previously built persistent map instances.
+     *
+     * Builder is backed by the same underlying data structure as the persistent map it was created from.
+     * Thus, [builder] and [build] methods take constant time passing the backing storage to the
+     * new builder and persistent map instances, respectively.
+     *
+     * The builder tracks which nodes in the structure are shared with the persistent map,
+     * and which are owned by it exclusively. It owns the nodes it copied during modification
+     * operations and avoids copying them on subsequent modifications.
+     *
+     * When [build] is called the builder forgets about all owned nodes it had created.
+     */
     interface Builder<K, V>: MutableMap<K, V> {
+        /**
+         * Returns a persistent map with the same contents as this builder.
+         *
+         * This method can be called multiple times.
+         *
+         * If operations applied on this builder have caused no modifications:
+         * - on the first call it returns the same persistent map instance this builder was obtained from.
+         * - on subsequent calls it returns the same previously returned persistent map instance.
+         */
         fun build(): PersistentMap<K, V>
     }
 
+    /**
+     * Returns a new builder with the same contents as this map.
+     *
+     * The builder can be used to efficiently perform multiple modification operations.
+     */
     fun builder(): Builder<K, @UnsafeVariance V>
 }