From fc7b1c861164f037dd87f2eb825b51d97cc3a17f Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Fri, 21 Oct 2016 23:11:46 +0300 Subject: [PATCH] KDoc for mutable abstract collections. Document abstract overrides. --- .../collections/AbstractMutableCollection.kt | 6 ++++- .../core/collections/AbstractMutableList.kt | 16 +++++++++++ .../core/collections/AbstractMutableMap.kt | 8 ++++++ .../core/collections/AbstractMutableSet.kt | 13 +++++++++ .../collections/AbstractMutableCollection.kt | 14 ++++++++++ .../kotlin/collections/AbstractMutableList.kt | 27 +++++++++++++++++++ .../kotlin/collections/AbstractMutableMap.kt | 16 +++++++++++ .../kotlin/collections/AbstractMutableSet.kt | 13 +++++++++ 8 files changed, 112 insertions(+), 1 deletion(-) diff --git a/js/js.libraries/src/core/collections/AbstractMutableCollection.kt b/js/js.libraries/src/core/collections/AbstractMutableCollection.kt index 51a4ea583c1..5ba14911096 100644 --- a/js/js.libraries/src/core/collections/AbstractMutableCollection.kt +++ b/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 protected constructor() : AbstractCollection(), MutableCollection { abstract override fun add(element: E): Boolean diff --git a/js/js.libraries/src/core/collections/AbstractMutableList.kt b/js/js.libraries/src/core/collections/AbstractMutableList.kt index 69c75045dc6..82520388df6 100644 --- a/js/js.libraries/src/core/collections/AbstractMutableList.kt +++ b/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 protected constructor() : AbstractMutableCollection(), MutableList { protected var modCount: Int = 0 @@ -79,6 +84,9 @@ public abstract class AbstractMutableList protected constructor() : AbstractM override fun subList(fromIndex: Int, toIndex: Int): MutableList = 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 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 protected constructor() : AbstractM return AbstractList.orderedEquals(this, other) } + /** + * Returns the hash code value for this list. + */ override fun hashCode(): Int = AbstractList.orderedHashCode(this) diff --git a/js/js.libraries/src/core/collections/AbstractMutableMap.kt b/js/js.libraries/src/core/collections/AbstractMutableMap.kt index 1e935455de3..cb531f6fb3c 100644 --- a/js/js.libraries/src/core/collections/AbstractMutableMap.kt +++ b/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 protected constructor() : AbstractMap(), MutableMap { /** diff --git a/js/js.libraries/src/core/collections/AbstractMutableSet.kt b/js/js.libraries/src/core/collections/AbstractMutableSet.kt index aa9bb6b7926..7692853afb1 100644 --- a/js/js.libraries/src/core/collections/AbstractMutableSet.kt +++ b/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 protected constructor() : AbstractMutableCollection(), MutableSet { + /** + * 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) } \ No newline at end of file diff --git a/libraries/stdlib/src/kotlin/collections/AbstractMutableCollection.kt b/libraries/stdlib/src/kotlin/collections/AbstractMutableCollection.kt index b95ea5ba888..fb164c990c2 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractMutableCollection.kt +++ b/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 protected constructor() : MutableCollection, AbstractCollection() { + /** + * 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 } \ No newline at end of file diff --git a/libraries/stdlib/src/kotlin/collections/AbstractMutableList.kt b/libraries/stdlib/src/kotlin/collections/AbstractMutableList.kt index 45e254affd6..c98492db9d9 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractMutableList.kt +++ b/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 protected constructor() : MutableList, AbstractList() { + /** + * 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) } \ No newline at end of file diff --git a/libraries/stdlib/src/kotlin/collections/AbstractMutableMap.kt b/libraries/stdlib/src/kotlin/collections/AbstractMutableMap.kt index 739c71eefab..6920156c16b 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractMutableMap.kt +++ b/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 protected constructor() : MutableMap, AbstractMap() { + /** + * 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? } \ No newline at end of file diff --git a/libraries/stdlib/src/kotlin/collections/AbstractMutableSet.kt b/libraries/stdlib/src/kotlin/collections/AbstractMutableSet.kt index d0fe5edbe74..5a41f931edd 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractMutableSet.kt +++ b/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 protected constructor() : MutableSet, AbstractSet() { + /** + * 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 } \ No newline at end of file