From 287a513f236df26bac16fe79e8edc20a77919ed5 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Fri, 21 Oct 2016 23:12:10 +0300 Subject: [PATCH] Provide KDoc for js collection implementations. --- .../src/core/collections/ArrayList.kt | 14 ++++++++++ .../core/collections/EqualityComparator.kt | 7 ++--- .../src/core/collections/HashMap.kt | 24 +++++++++++++++- .../src/core/collections/HashSet.kt | 28 ++++++++++++++++--- .../src/core/collections/LinkedHashMap.kt | 25 ++++++++++++++++- .../src/core/collections/LinkedHashSet.kt | 28 +++++++++++++++++-- .../src/core/collections/RandomAccess.kt | 3 ++ 7 files changed, 116 insertions(+), 13 deletions(-) diff --git a/js/js.libraries/src/core/collections/ArrayList.kt b/js/js.libraries/src/core/collections/ArrayList.kt index c46864f5927..182d1a8b615 100644 --- a/js/js.libraries/src/core/collections/ArrayList.kt +++ b/js/js.libraries/src/core/collections/ArrayList.kt @@ -16,9 +16,23 @@ package kotlin.collections +/** + * Provides a [MutableList] implementation, which uses a resizable array as its backing storage. + * + * This implementation doesn't provide a way to manage capacity, as backing JS array is resizeable itself. + * There is no speed advantage to pre-allocating array sizes in JavaScript, so this implementation does not include any of the + * capacity and "growth increment" concepts. + */ public open class ArrayList internal constructor(private var array: Array) : AbstractMutableList(), RandomAccess { + /** + * Creates an empty [ArrayList]. + * @param capacity initial capacity (ignored) + */ public constructor(capacity: Int = 0) : this(emptyArray()) {} + /** + * Creates an [ArrayList] filled from the [elements] collection. + */ public constructor(elements: Collection) : this(elements.toTypedArray()) {} /** Does nothing in this ArrayList implementation. */ diff --git a/js/js.libraries/src/core/collections/EqualityComparator.kt b/js/js.libraries/src/core/collections/EqualityComparator.kt index 442db33d0f0..d565dfbf2c5 100644 --- a/js/js.libraries/src/core/collections/EqualityComparator.kt +++ b/js/js.libraries/src/core/collections/EqualityComparator.kt @@ -18,14 +18,13 @@ package kotlin.collections internal interface EqualityComparator { /** - * Subclasses must override to return a whether or not two keys or values are - * equal. + * Subclasses must override to return a value indicating + * whether or not two keys or values are equal. */ abstract fun equals(value1: Any?, value2: Any?): Boolean /** - * Subclasses must override to return a hash code for a given key. The key is - * guaranteed to be non-null and not a String. + * Subclasses must override to return the hash code of a given key. */ abstract fun getHashCode(value: Any?): Int diff --git a/js/js.libraries/src/core/collections/HashMap.kt b/js/js.libraries/src/core/collections/HashMap.kt index b0b0132e94e..1c225c094c2 100644 --- a/js/js.libraries/src/core/collections/HashMap.kt +++ b/js/js.libraries/src/core/collections/HashMap.kt @@ -23,6 +23,11 @@ package kotlin.collections import kotlin.collections.Map.Entry import kotlin.collections.MutableMap.MutableEntry +/** + * Hash table based implementation of the [MutableMap] interface. + * + * This implementation makes no guarantees regarding the order of enumeration of [keys], [elements] and [entries] collections. + */ public open class HashMap : AbstractMutableMap { private inner class EntrySet : AbstractMutableSet>() { @@ -60,14 +65,28 @@ public open class HashMap : AbstractMutableMap { this.equality = internalMap.equality } + /** + * Constructs an empty [HashMap] instance. + */ constructor() : this(InternalHashCodeMap(EqualityComparator.HashCode)) + /** + * Constructs an empty [HashMap] instance. + * + * @param initialCapacity the initial capacity (ignored) + * @param loadFactor the load factor (ignored) + * + * @throws IllegalArgumentException if the initial capacity or load factor are negative + */ constructor(initialCapacity: Int, loadFactor: Float = 0f) : this() { // This implementation of HashMap has no need of load factors or capacities. require(initialCapacity >= 0) { "Negative initial capacity" } require(loadFactor >= 0) { "Non-positive load factor" } } + /** + * Constructs an instance of [HashMap] filled with the contents of the specified [original] map. + */ constructor(original: Map) : this() { this.putAll(original) } @@ -101,7 +120,10 @@ public open class HashMap : AbstractMutableMap { } - +/** + * Constructs the specialized implementation of [HashMap] with [String] keys, which stores the keys as properties of + * JS object without hashing them. + */ public fun stringMapOf(vararg pairs: Pair): HashMap { return HashMap(InternalStringMap(EqualityComparator.HashCode)).apply { putAll(pairs) } } \ No newline at end of file diff --git a/js/js.libraries/src/core/collections/HashSet.kt b/js/js.libraries/src/core/collections/HashSet.kt index fde000be732..1a15197f305 100644 --- a/js/js.libraries/src/core/collections/HashSet.kt +++ b/js/js.libraries/src/core/collections/HashSet.kt @@ -20,20 +20,36 @@ package kotlin.collections - +/** + * The implementation of the [MutableSet] interface, backed by a [HashMap] instance. + */ public open class HashSet : AbstractMutableSet { private val map: HashMap + /** + * Constructs a new empty [HashSet]. + */ constructor() { map = HashMap() } - constructor(c: Collection) { - map = HashMap(c.size) - addAll(c) + /** + * Constructs a new [HashSet] filled with the elements of the specified collection. + */ + constructor(elements: Collection) { + map = HashMap(elements.size) + addAll(elements) } + /** + * Constructs a new empty [HashSet]. + * + * @param initialCapacity the initial capacity (ignored) + * @param loadFactor the load factor (ignored) + * + * @throws IllegalArgumentException if the initial capacity or load factor are negative + */ constructor(initialCapacity: Int, loadFactor: Float = 0.0f) { map = HashMap(initialCapacity, loadFactor) } @@ -73,6 +89,10 @@ public open class HashSet : AbstractMutableSet { } +/** + * Creates a new instance of the specialized implementation of [HashSet] with the specified [String] elements, + * which elements the keys as properties of JS object without hashing them. + */ public fun stringSetOf(vararg elements: String): HashSet { return HashSet(stringMapOf()).apply { addAll(elements) } } diff --git a/js/js.libraries/src/core/collections/LinkedHashMap.kt b/js/js.libraries/src/core/collections/LinkedHashMap.kt index d7ad962c444..b9842a51ff9 100644 --- a/js/js.libraries/src/core/collections/LinkedHashMap.kt +++ b/js/js.libraries/src/core/collections/LinkedHashMap.kt @@ -21,6 +21,12 @@ package kotlin.collections import kotlin.collections.MutableMap.MutableEntry +/** + * Hash table based implementation of the [MutableMap] interface, which additionally preserves the insertion order + * of entries during the iteration. + * + * The insertion order is preserved by maintaining a doubly-linked list of all of its entries. + */ public open class LinkedHashMap : HashMap, Map { /** @@ -160,6 +166,9 @@ public open class LinkedHashMap : HashMap, Map { */ private val map: HashMap> + /** + * Constructs an empty [LinkedHashMap] instance. + */ constructor() : super() { map = HashMap>() } @@ -168,10 +177,21 @@ public open class LinkedHashMap : HashMap, Map { map = backingMap as HashMap> } + /** + * Constructs an empty [LinkedHashMap] instance. + * + * @param initialCapacity the initial capacity (ignored) + * @param loadFactor the load factor (ignored) + * + * @throws IllegalArgumentException if the initial capacity or load factor are negative + */ constructor(initialCapacity: Int, loadFactor: Float = 0f) : super(initialCapacity, loadFactor) { map = HashMap>() } + /** + * Constructs an instance of [LinkedHashMap] filled with the contents of the specified [original] map. + */ constructor(original: Map) { map = HashMap>() this.putAll(original) @@ -231,7 +251,10 @@ public open class LinkedHashMap : HashMap, Map { } - +/** + * Constructs the specialized implementation of [LinkedHashMap] with [String] keys, which stores the keys as properties of + * JS object without hashing them. + */ public fun linkedStringMapOf(vararg pairs: Pair): LinkedHashMap { return LinkedHashMap(stringMapOf()).apply { putAll(pairs) } } \ No newline at end of file diff --git a/js/js.libraries/src/core/collections/LinkedHashSet.kt b/js/js.libraries/src/core/collections/LinkedHashSet.kt index 246078498b3..f31b25efc94 100644 --- a/js/js.libraries/src/core/collections/LinkedHashSet.kt +++ b/js/js.libraries/src/core/collections/LinkedHashSet.kt @@ -20,16 +20,34 @@ package kotlin.collections +/** + * The implementation of the [MutableSet] interface, backed by a [LinkedHashMap] instance. + * + * This implementation preserves the insertion order of elements during the iteration. + */ public open class LinkedHashSet : HashSet { internal constructor(map: LinkedHashMap) : super(map) + /** + * Constructs a new empty [LinkedHashSet]. + */ constructor() : super(LinkedHashMap()) - constructor(c: Collection) : super(LinkedHashMap()) { - addAll(c) + /** + * Constructs a new [LinkedHashSet] filled with the elements of the specified collection. + */ + constructor(elements: Collection) : super(LinkedHashMap()) { + addAll(elements) } - + /** + * Constructs a new empty [LinkedHashSet]. + * + * @param initialCapacity the initial capacity (ignored) + * @param loadFactor the load factor (ignored) + * + * @throws IllegalArgumentException if the initial capacity or load factor are negative + */ constructor(initialCapacity: Int, loadFactor: Float = 0.0f) : super(LinkedHashMap(initialCapacity, loadFactor)) // public override fun clone(): Any { @@ -38,6 +56,10 @@ public open class LinkedHashSet : HashSet { } +/** + * Creates a new instance of the specialized implementation of [LinkedHashSet] with the specified [String] elements, + * which elements the keys as properties of JS object without hashing them. + */ public fun linkedStringSetOf(vararg elements: String): LinkedHashSet { return LinkedHashSet(linkedStringMapOf()).apply { addAll(elements) } } diff --git a/js/js.libraries/src/core/collections/RandomAccess.kt b/js/js.libraries/src/core/collections/RandomAccess.kt index a94d131b63d..6da6377f9a5 100644 --- a/js/js.libraries/src/core/collections/RandomAccess.kt +++ b/js/js.libraries/src/core/collections/RandomAccess.kt @@ -16,4 +16,7 @@ package kotlin.collections +/** + * Marker interface indicating that the [List] implementation supports fast indexed access. + */ public interface RandomAccess \ No newline at end of file