KDoc for read-only abstract collections

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

@@ -15,6 +15,11 @@
  */
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the read-only [Collection] interface.
+ *
+* @param E the type of elements contained in the collection. The collection is covariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractCollection<out E> protected constructor() : Collection<E> {
     abstract override val size: Int

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

@@ -20,6 +20,13 @@
 
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the read-only [List] interface.
+ *
+ * This class is intended to help implementing read-only lists so it doesn't support concurrent modification tracking.
+ *
+ * @param E the type of elements contained in the list. The list is covariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractList<out E> protected constructor() : AbstractCollection<E>(), List<E> {
     abstract override val size: Int
@@ -54,6 +61,11 @@ public abstract class AbstractList<out E> protected constructor() : AbstractColl
         override val size: Int get() = _size
     }
 
+    /**
+     * Compares this list with other 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
@@ -61,6 +73,9 @@ public abstract class AbstractList<out E> protected constructor() : AbstractColl
         return orderedEquals(this, other)
     }
 
+    /**
+     * Returns the hash code value for this list.
+     */
     override fun hashCode(): Int = orderedHashCode(this)
 
     private open inner class IteratorImpl : Iterator<E> {
@@ -76,7 +91,7 @@ public abstract class AbstractList<out E> protected constructor() : AbstractColl
     }
 
     /**
-     * Implementation of `MutableListIterator` for abstract lists.
+     * Implementation of [ListIterator] for abstract lists.
      */
     private open inner class ListIteratorImpl(index: Int) : IteratorImpl(), ListIterator<E> {
 

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

@@ -20,6 +20,14 @@
 
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the read-only [Map] interface.
+ *
+ * The implementor is required to implement [entries] property, which should return read-only set of map entries.
+ *
+ * @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 covariant on its value type.
+*/
 @SinceKotlin("1.1")
 public abstract class AbstractMap<K, out V> protected constructor() : Map<K, V> {
 
@@ -48,6 +56,12 @@ public abstract class AbstractMap<K, out V> protected constructor() : Map<K, V>
         return true
     }
 
+
+    /**
+     * Compares this map with other instance with the ordered structural equality.
+     *
+     * @return true, if [other] instance is a [Map] of the same size, all entries of which are contained in the [entries] set of this map.
+     */
     override fun equals(other: Any?): Boolean {
         if (other === this) return true
         if (other !is Map<*, *>) return false
@@ -58,11 +72,23 @@ public abstract class AbstractMap<K, out V> protected constructor() : Map<K, V>
 
     override operator fun get(key: K): V? = implFindEntry(key)?.value
 
+
+    /**
+     * Returns the hash code value for this map.
+     *
+     * It is the same as the hashCode of [entries] set.
+     */
     override fun hashCode(): Int = entries.hashCode()
 
     override fun isEmpty(): Boolean = size == 0
     override val size: Int get() = entries.size
 
+    /**
+     * Returns a read-only [Set] of all keys in this map.
+     *
+     * Accessing this property first time creates a keys view from [entries].
+     * All subsequent accesses just return the created instance.
+     */
     private @Volatile var _keys: Set<K>? = null
     override val keys: Set<K> get() {
         if (_keys == null) {
@@ -89,6 +115,12 @@ public abstract class AbstractMap<K, out V> protected constructor() : Map<K, V>
 
     private fun toString(o: Any?): String = if (o === this) "(this Map)" else o.toString()
 
+    /**
+     * Returns a read-only [Collection] of all values in this map.
+     *
+     * Accessing this property first time creates a values view from [entries].
+     * All subsequent accesses just return the created instance.
+     */
     private @Volatile var _values: Collection<V>? = null
     override val values: Collection<V> get() {
         if (_values == null) {

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

@@ -15,15 +15,30 @@
  */
 package kotlin.collections
 
+/**
+ * Provides a skeletal implementation of the read-only [Set] interface.
+ *
+ * This class is intended to help implementing read-only sets so it doesn't support concurrent modification tracking.
+ *
+ * @param E the type of elements contained in the set. The set is covariant on its element type.
+ */
 @SinceKotlin("1.1")
 public abstract class AbstractSet<out E> protected constructor() : AbstractCollection<E>(), Set<E> {
 
+    /**
+     * Compares this set with other 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 setEquals(this, other)
     }
 
+    /**
+     * Returns the hash code value for this set.
+     */
     override fun hashCode(): Int = unorderedHashCode(this)
 
     internal companion object {