From ef5e53b37b50dba69b1bf264704b7d42a96d4868 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Wed, 19 Oct 2016 20:38:09 +0300 Subject: [PATCH] KDoc for read-only abstract collections --- .../kotlin/collections/AbstractCollection.kt | 5 +++ .../src/kotlin/collections/AbstractList.kt | 17 +++++++++- .../src/kotlin/collections/AbstractMap.kt | 32 +++++++++++++++++++ .../src/kotlin/collections/AbstractSet.kt | 15 +++++++++ 4 files changed, 68 insertions(+), 1 deletion(-) diff --git a/libraries/stdlib/src/kotlin/collections/AbstractCollection.kt b/libraries/stdlib/src/kotlin/collections/AbstractCollection.kt index 4ffb177adb0..2df9162114e 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractCollection.kt +++ b/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 protected constructor() : Collection { abstract override val size: Int diff --git a/libraries/stdlib/src/kotlin/collections/AbstractList.kt b/libraries/stdlib/src/kotlin/collections/AbstractList.kt index d11e9dd3071..66a00e8b59c 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractList.kt +++ b/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 protected constructor() : AbstractCollection(), List { abstract override val size: Int @@ -54,6 +61,11 @@ public abstract class AbstractList 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 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 { @@ -76,7 +91,7 @@ public abstract class AbstractList protected constructor() : AbstractColl } /** - * Implementation of `MutableListIterator` for abstract lists. + * Implementation of [ListIterator] for abstract lists. */ private open inner class ListIteratorImpl(index: Int) : IteratorImpl(), ListIterator { diff --git a/libraries/stdlib/src/kotlin/collections/AbstractMap.kt b/libraries/stdlib/src/kotlin/collections/AbstractMap.kt index 0d0d8d4d312..890d262bdaf 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractMap.kt +++ b/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 protected constructor() : Map { @@ -48,6 +56,12 @@ public abstract class AbstractMap protected constructor() : Map 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 protected constructor() : Map 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? = null override val keys: Set get() { if (_keys == null) { @@ -89,6 +115,12 @@ public abstract class AbstractMap protected constructor() : Map 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? = null override val values: Collection get() { if (_values == null) { diff --git a/libraries/stdlib/src/kotlin/collections/AbstractSet.kt b/libraries/stdlib/src/kotlin/collections/AbstractSet.kt index 41ce2a02b18..500ab16f95d 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractSet.kt +++ b/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 protected constructor() : AbstractCollection(), Set { + /** + * 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 {