KDoc for mutable abstract collections.

Document abstract overrides.

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
 }