KDoc for mutable abstract collections.

Document abstract overrides.

js/js.libraries/src/core/collections/AbstractMutableCollection.kt

@@ -16,7 +16,11 @@
 
 package kotlin.collections
 
-
+/**
+ * Provides a skeletal implementation of the [MutableCollection] interface.
+ *
+ * @param E the type of elements contained in the collection. The collection is invariant on its element type.
+ */
 public abstract class AbstractMutableCollection<E> protected constructor() : AbstractCollection<E>(), MutableCollection<E> {
 
     abstract override fun add(element: E): Boolean

js/js.libraries/src/core/collections/AbstractMutableList.kt

@@ -21,6 +21,11 @@
 
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the [MutableList] interface.
+ *
+ * @param E the type of elements contained in the list. The list is invariant on its element type.
+ */
 public abstract class AbstractMutableList<E> protected constructor() : AbstractMutableCollection<E>(), MutableList<E> {
     protected var modCount: Int = 0
 
@@ -79,6 +84,9 @@ public abstract class AbstractMutableList<E> protected constructor() : AbstractM
 
     override fun subList(fromIndex: Int, toIndex: Int): MutableList<E> = SubList(this, fromIndex, toIndex)
 
+    /**
+     * Removes the range of elements from this list starting from [fromIndex] and ending with but not including [toIndex].
+     */
     protected open fun removeRange(fromIndex: Int, toIndex: Int) {
         val iterator = listIterator(fromIndex)
         repeat(toIndex - fromIndex) {
@@ -87,6 +95,11 @@ public abstract class AbstractMutableList<E> protected constructor() : AbstractM
         }
     }
 
+    /**
+     * Compares this list with another list instance with the ordered structural equality.
+     *
+     * @return true, if [other] instance is a [List] of the same size, which contains the same elements in the same order.
+     */
     override fun equals(other: Any?): Boolean {
         if (other === this) return true
         if (other !is List<*>) return false
@@ -94,6 +107,9 @@ public abstract class AbstractMutableList<E> protected constructor() : AbstractM
         return AbstractList.orderedEquals(this, other)
     }
 
+    /**
+     * Returns the hash code value for this list.
+     */
     override fun hashCode(): Int = AbstractList.orderedHashCode(this)
 
 

js/js.libraries/src/core/collections/AbstractMutableMap.kt

@@ -20,6 +20,14 @@
 
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the [MutableMap] interface.
+ *
+ * The implementor is required to implement the [entries] property, which should return mutable set of map entries, and the [put] function.
+ *
+ * @param K the type of map keys. The map is invariant on its key type.
+ * @param V the type of map values. The map is invariant on its value type.
+ */
 public abstract class AbstractMutableMap<K, V> protected constructor() : AbstractMap<K, V>(), MutableMap<K, V> {
 
     /**

js/js.libraries/src/core/collections/AbstractMutableSet.kt

@@ -15,14 +15,27 @@
  */
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the [MutableSet] interface.
+ *
+ * @param E the type of elements contained in the set. The set is invariant on its element type.
+ */
 public abstract class AbstractMutableSet<E> protected constructor() : AbstractMutableCollection<E>(), MutableSet<E> {
 
+    /**
+     * Compares this set with another set instance with the unordered structural equality.
+     *
+     * @return true, if [other] instance is a [Set] of the same size, all elements of which are contained in this set.
+     */
     override fun equals(other: Any?): Boolean {
         if (other === this) return true
         if (other !is Set<*>) return false
         return AbstractSet.setEquals(this, other)
     }
 
+    /**
+     * Returns the hash code value for this set.
+     */
     override fun hashCode(): Int = AbstractSet.unorderedHashCode(this)
 
 }

libraries/stdlib/src/kotlin/collections/AbstractMutableCollection.kt

@@ -3,7 +3,21 @@ package kotlin.collections
 
 import java.util.AbstractCollection
 
+/**
+ * Provides a skeletal implementation of the [MutableCollection] interface.
+ *
+ * @param E the type of elements contained in the collection. The collection is invariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractMutableCollection<E> protected constructor() : MutableCollection<E>, AbstractCollection<E>() {
+    /**
+     * Adds the specified element to the collection.
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+     *
+     * @return `true` if the element has been added, `false` if the collection does not support duplicates
+     * and the element is already contained in the collection.
+     */
     abstract override fun add(element: E): Boolean
 }

libraries/stdlib/src/kotlin/collections/AbstractMutableList.kt

@@ -3,9 +3,36 @@ package kotlin.collections
 
 import java.util.AbstractList
 
+/**
+ * Provides a skeletal implementation of the [MutableList] interface.
+ *
+ * @param E the type of elements contained in the list. The list is invariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractMutableList<E> protected constructor() : MutableList<E>, AbstractList<E>() {
+    /**
+     * Replaces the element at the specified position in this list with the specified element.
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+
+     * @return the element previously at the specified position.
+     */
     abstract override fun set(index: Int, element: E): E
+    /**
+     * Removes an element at the specified [index] from the list.
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+     *
+     * @return the element that has been removed.
+     */
     abstract override fun removeAt(index: Int): E
+    /**
+     * Inserts an element into the list at the specified [index].
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+     */
     abstract override fun add(index: Int, element: E)
 }

libraries/stdlib/src/kotlin/collections/AbstractMutableMap.kt

@@ -3,7 +3,23 @@ package kotlin.collections
 
 import java.util.AbstractMap
 
+/**
+ * Provides a skeletal implementation of the [MutableMap] interface.
+ *
+ * The implementor is required to implement [entries] property, which should return mutable set of map entries, and [put] function.
+ *
+ * @param K the type of map keys. The map is invariant on its key type.
+ * @param V the type of map values. The map is invariant on its value type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractMutableMap<K, V> protected constructor() : MutableMap<K, V>, AbstractMap<K, V>() {
+    /**
+     * Associates the specified [value] with the specified [key] in the map.
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+     *
+     * @return the previous value associated with the key, or `null` if the key was not present in the map.
+     */
     abstract override fun put(key: K, value: V): V?
 }

libraries/stdlib/src/kotlin/collections/AbstractMutableSet.kt

@@ -3,7 +3,20 @@ package kotlin.collections
 
 import java.util.AbstractSet
 
+/**
+ * Provides a skeletal implementation of the [MutableSet] interface.
+ *
+ * @param E the type of elements contained in the set. The set is invariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractMutableSet<E> protected constructor() : MutableSet<E>, AbstractSet<E>() {
+    /**
+     * Adds the specified element to the set.
+     *
+     * This method is redeclared as abstract, because it's not implemented in the base class,
+     * so it must be always overridden in the concrete mutable collection implementation.
+     *
+     * @return `true` if the element has been added, `false` if the element is already contained in the set.
+     */
     abstract override fun add(element: E): Boolean
 }