From f107559a3ce099e2e01a77a844b59eec9e49f86d Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Mon, 30 Nov 2015 14:42:09 +0300 Subject: [PATCH] Docs: proper pluralization of 'entry' --- libraries/stdlib/src/generated/_Maps.kt | 14 ++++++------ .../src/templates/Aggregates.kt | 18 +++++++-------- .../src/templates/Filtering.kt | 12 +++++----- .../src/templates/Mapping.kt | 4 ++-- .../src/templates/Ordering.kt | 2 +- .../src/templates/Sequence.kt | 4 ++-- .../kotlin-stdlib-gen/src/templates/Sets.kt | 10 ++++----- .../src/templates/Snapshots.kt | 22 +++++++++---------- .../src/templates/engine/DocExtensions.kt | 5 +++++ 9 files changed, 48 insertions(+), 43 deletions(-) diff --git a/libraries/stdlib/src/generated/_Maps.kt b/libraries/stdlib/src/generated/_Maps.kt index 3a4fb8c8526..a87c931bdbe 100644 --- a/libraries/stdlib/src/generated/_Maps.kt +++ b/libraries/stdlib/src/generated/_Maps.kt @@ -88,7 +88,7 @@ public inline fun > Map.mapTo(destina } /** - * Returns `true` if all entrys match the given [predicate]. + * Returns `true` if all entries match the given [predicate]. */ public inline fun Map.all(predicate: (Map.Entry) -> Boolean): Boolean { for (element in this) if (!predicate(element)) return false @@ -112,14 +112,14 @@ public inline fun Map.any(predicate: (Map.Entry) -> Boolean): } /** - * Returns the number of entrys in this map. + * Returns the number of entries in this map. */ public fun Map.count(): Int { return size } /** - * Returns the number of entrys matching the given [predicate]. + * Returns the number of entries matching the given [predicate]. */ public inline fun Map.count(predicate: (Map.Entry) -> Boolean): Int { var count = 0 @@ -173,7 +173,7 @@ public inline fun > Map.minBy(selector: (Map.Entry } /** - * Returns `true` if the map has no entrys. + * Returns `true` if the map has no entries. */ public fun Map.none(): Boolean { for (element in this) return false @@ -181,7 +181,7 @@ public fun Map.none(): Boolean { } /** - * Returns `true` if no entrys match the given [predicate]. + * Returns `true` if no entries match the given [predicate]. */ public inline fun Map.none(predicate: (Map.Entry) -> Boolean): Boolean { for (element in this) if (predicate(element)) return false @@ -189,14 +189,14 @@ public inline fun Map.none(predicate: (Map.Entry) -> Boolean) } /** - * Creates an [Iterable] instance that wraps the original map returning its entrys when being iterated. + * Creates an [Iterable] instance that wraps the original map returning its entries when being iterated. */ public fun Map.asIterable(): Iterable> { return entries } /** - * Creates a [Sequence] instance that wraps the original map returning its entrys when being iterated. + * Creates a [Sequence] instance that wraps the original map returning its entries when being iterated. */ public fun Map.asSequence(): Sequence> { return object : Sequence> { diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt index 195d84a5250..1b39d1b7b15 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt @@ -7,7 +7,7 @@ fun aggregates(): List { templates add f("all(predicate: (T) -> Boolean)") { inline(true) - doc { f -> "Returns `true` if all ${f.element}s match the given [predicate]." } + doc { f -> "Returns `true` if all ${f.element.pluralize()} match the given [predicate]." } returns("Boolean") body { """ @@ -22,7 +22,7 @@ fun aggregates(): List { templates add f("none(predicate: (T) -> Boolean)") { inline(true) - doc { f -> "Returns `true` if no ${f.element}s match the given [predicate]." } + doc { f -> "Returns `true` if no ${f.element.pluralize()} match the given [predicate]." } returns("Boolean") body { """ @@ -35,7 +35,7 @@ fun aggregates(): List { } templates add f("none()") { - doc { f -> "Returns `true` if the ${f.collection} has no ${f.element}s." } + doc { f -> "Returns `true` if the ${f.collection} has no ${f.element.pluralize()}." } returns("Boolean") body { """ @@ -78,7 +78,7 @@ fun aggregates(): List { templates add f("count(predicate: (T) -> Boolean)") { inline(true) - doc { f -> "Returns the number of ${f.element}s matching the given [predicate]." } + doc { f -> "Returns the number of ${f.element.pluralize()} matching the given [predicate]." } returns("Int") body { """ @@ -92,7 +92,7 @@ fun aggregates(): List { } templates add f("count()") { - doc { f -> "Returns the number of ${f.element}s in this ${f.collection}." } + doc { f -> "Returns the number of ${f.element.pluralize()} in this ${f.collection}." } returns("Int") body { """ @@ -146,7 +146,7 @@ fun aggregates(): List { } templates add f("min()") { - doc { f -> "Returns the smallest ${f.element} or `null` if there are no ${f.element}s." } + doc { f -> "Returns the smallest ${f.element} or `null` if there are no ${f.element.pluralize()}." } returns("T?") exclude(PrimitiveType.Boolean) typeParam("T : Comparable") @@ -180,7 +180,7 @@ fun aggregates(): List { templates add f("minBy(selector: (T) -> R)") { inline(true) - doc { f -> "Returns the first ${f.element} yielding the smallest value of the given function or `null` if there are no ${f.element}s." } + doc { f -> "Returns the first ${f.element} yielding the smallest value of the given function or `null` if there are no ${f.element.pluralize()}." } typeParam("R : Comparable") typeParam("T : Any") returns("T?") @@ -250,7 +250,7 @@ fun aggregates(): List { } templates add f("max()") { - doc { f -> "Returns the largest ${f.element} or `null` if there are no ${f.element}s." } + doc { f -> "Returns the largest ${f.element} or `null` if there are no ${f.element.pluralize()}." } returns("T?") exclude(PrimitiveType.Boolean) typeParam("T : Comparable") @@ -286,7 +286,7 @@ fun aggregates(): List { templates add f("maxBy(selector: (T) -> R)") { inline(true) - doc { f -> "Returns the first ${f.element} yielding the largest value of the given function or `null` if there are no ${f.element}s." } + doc { f -> "Returns the first ${f.element} yielding the largest value of the given function or `null` if there are no ${f.element.pluralize()}." } typeParam("R : Comparable") typeParam("T : Any") returns("T?") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt index 12767e5fecf..607f283d3dd 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt @@ -349,7 +349,7 @@ fun filtering(): List { templates add f("filter(predicate: (T) -> Boolean)") { inline(true) - doc { f -> "Returns a ${f.mapResult} containing only ${f.element}s matching the given [predicate]." } + doc { f -> "Returns a ${f.mapResult} containing only ${f.element.pluralize()} matching the given [predicate]." } returns("List") body { """ @@ -373,7 +373,7 @@ fun filtering(): List { templates add f("filterTo(destination: C, predicate: (T) -> Boolean)") { inline(true) - doc { f -> "Appends all ${f.element}s matching the given [predicate] to the given [destination]." } + doc { f -> "Appends all ${f.element.pluralize()} matching the given [predicate] to the given [destination]." } typeParam("C : TCollection") returns("C") @@ -399,7 +399,7 @@ fun filtering(): List { templates add f("filterIndexed(predicate: (Int, T) -> Boolean)") { inline(true) - doc { f -> "Returns a ${f.mapResult} containing only ${f.element}s matching the given [predicate]." } + doc { f -> "Returns a ${f.mapResult} containing only ${f.element.pluralize()} matching the given [predicate]." } returns("List") body { """ @@ -427,7 +427,7 @@ fun filtering(): List { include(CharSequences) - doc { f -> "Appends all ${f.element}s matching the given [predicate] to the given [destination]." } + doc { f -> "Appends all ${f.element.pluralize()} matching the given [predicate] to the given [destination]." } typeParam("C : TCollection") returns("C") @@ -542,7 +542,7 @@ fun filtering(): List { """ } - doc(CharSequences, Strings) { f -> "Returns a ${f.collection} containing ${f.element}s of the original ${f.collection} at specified [indices]." } + doc(CharSequences, Strings) { f -> "Returns a ${f.collection} containing ${f.element.pluralize()} of the original ${f.collection} at specified [indices]." } returns(CharSequences, Strings) { "SELF" } body(CharSequences, Strings) { f -> """ @@ -574,7 +574,7 @@ fun filtering(): List { """ } - doc(CharSequences, Strings) { f -> "Returns a ${f.collection} containing ${f.element}s of the original ${f.collection} at the specified range of [indices]." } + doc(CharSequences, Strings) { f -> "Returns a ${f.collection} containing ${f.element.pluralize()} of the original ${f.collection} at the specified range of [indices]." } returns(CharSequences, Strings) { "SELF" } body(CharSequences, Strings) { f -> """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt index 8c535a3856c..59dc9c6fbed 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt @@ -289,7 +289,7 @@ fun mapping(): List { deprecate(Strings) { forBinaryCompatibility } include(CharSequences, Strings) - doc { f -> "Returns a map of the ${f.element}s in original ${f.collection} grouped by the key returned by the given [selector] function." } + doc { f -> "Returns a map of the ${f.element.pluralize()} in original ${f.collection} grouped by the key returned by the given [selector] function." } typeParam("K") returns("Map>") body { "return groupByTo(LinkedHashMap>(), selector)" } @@ -301,7 +301,7 @@ fun mapping(): List { deprecate(Strings) { forBinaryCompatibility } include(CharSequences, Strings) typeParam("K") - doc { f -> "Appends ${f.element}s from original ${f.collection} grouped by the key returned by the given [selector] function to the given [map]." } + doc { f -> "Appends ${f.element.pluralize()} from original ${f.collection} grouped by the key returned by the given [selector] function to the given [map]." } returns("Map>") body { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt index bd6be80b77e..eaad1eb1943 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt @@ -6,7 +6,7 @@ fun ordering(): List { val templates = arrayListOf() templates add f("reverse()") { - doc { f -> "Reverses ${f.element}s in the ${f.collection} in-place." } + doc { f -> "Reverses ${f.element.pluralize()} in the ${f.collection} in-place." } only(Lists, ArraysOfObjects, ArraysOfPrimitives) customReceiver(Lists) { "MutableList" } returns { "Unit" } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt index ebb9eaaa29f..5258a669259 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt @@ -7,7 +7,7 @@ fun sequences(): List { templates add f("asIterable()") { only(Iterables, ArraysOfObjects, ArraysOfPrimitives, Sequences, CharSequences, Maps) - doc { f -> "Creates an [Iterable] instance that wraps the original ${f.collection} returning its ${f.element}s when being iterated." } + doc { f -> "Creates an [Iterable] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated." } returns("Iterable") body { f -> """ @@ -28,7 +28,7 @@ fun sequences(): List { templates add f("asSequence()") { include(Maps) - doc { f -> "Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element}s when being iterated." } + doc { f -> "Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated." } returns("Sequence") body { f -> """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt index e06f951e82a..5e129ac2ce1 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt @@ -7,7 +7,7 @@ fun sets(): List { templates add f("toMutableSet()") { exclude(Strings) - doc { f -> "Returns a mutable set containing all distinct ${f.element}s from the given ${f.collection}." } + doc { f -> "Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}." } returns("MutableSet") body { """ @@ -38,9 +38,9 @@ fun sets(): List { exclude(Strings) doc { f -> """ - Returns a ${f.mapResult} containing only distinct ${f.element}s from the given ${f.collection}. + Returns a ${f.mapResult} containing only distinct ${f.element.pluralize()} from the given ${f.collection}. - The ${f.element}s in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}. + The ${f.element.pluralize()} in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}. """ } @@ -54,10 +54,10 @@ fun sets(): List { exclude(Strings) doc { f -> """ - Returns a ${f.mapResult} containing only ${f.element}s from the given ${f.collection} + Returns a ${f.mapResult} containing only ${f.element.pluralize()} from the given ${f.collection} having distinct keys returned by the given [selector] function. - The ${f.element}s in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}. + The ${f.element.pluralize()} in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}. """ } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt index f2e26e2fc35..bd35dca5d88 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt @@ -8,7 +8,7 @@ fun snapshots(): List { templates add f("toCollection(destination: C)") { deprecate(Strings) { forBinaryCompatibility } include(CharSequences, Strings) - doc { f -> "Appends all ${f.element}s to the given [destination] collection." } + doc { f -> "Appends all ${f.element.pluralize()} to the given [destination] collection." } returns("C") typeParam("C : MutableCollection") body { @@ -22,7 +22,7 @@ fun snapshots(): List { } templates add f("toSet()") { - doc { f -> "Returns a [Set] of all ${f.element}s." } + doc { f -> "Returns a [Set] of all ${f.element.pluralize()}." } returns("Set") body { "return toCollection(LinkedHashSet(mapCapacity(collectionSizeOrDefault(12))))" } body(Sequences) { "return toCollection(LinkedHashSet())" } @@ -32,7 +32,7 @@ fun snapshots(): List { } templates add f("toHashSet()") { - doc { f -> "Returns a [HashSet] of all ${f.element}s." } + doc { f -> "Returns a [HashSet] of all ${f.element.pluralize()}." } returns("HashSet") body { "return toCollection(HashSet(mapCapacity(collectionSizeOrDefault(12))))" } body(Sequences) { "return toCollection(HashSet())" } @@ -45,7 +45,7 @@ fun snapshots(): List { deprecate(Strings) { forBinaryCompatibility } include(CharSequences, Strings) typeParam("T: Comparable") - doc { f -> "Returns a [SortedSet] of all ${f.element}s." } + doc { f -> "Returns a [SortedSet] of all ${f.element.pluralize()}." } returns("SortedSet") body { "return toCollection(TreeSet())" } } @@ -55,7 +55,7 @@ fun snapshots(): List { jvmOnly(true) doc { f -> """ - Returns a [SortedSet] of all ${f.element}s. + Returns a [SortedSet] of all ${f.element.pluralize()}. Elements in the set returned are sorted according to the given [comparator]. """ @@ -65,7 +65,7 @@ fun snapshots(): List { } templates add f("toArrayList()") { - doc { f -> "Returns an [ArrayList] of all ${f.element}s." } + doc { f -> "Returns an [ArrayList] of all ${f.element.pluralize()}." } returns("ArrayList") body { "return toCollection(ArrayList())" } body(Iterables) { @@ -105,7 +105,7 @@ fun snapshots(): List { templates add f("toList()") { deprecate(Strings) { forBinaryCompatibility } include(CharSequences, Strings) - doc { f -> "Returns a [List] containing all ${f.element}s." } + doc { f -> "Returns a [List] containing all ${f.element.pluralize()}." } returns("List") body { "return this.toArrayList()" } } @@ -132,9 +132,9 @@ fun snapshots(): List { typeParam("K") doc { f -> """ - Returns Map containing the ${f.element}s from the given ${f.collection} indexed by the key + Returns Map containing the ${f.element.pluralize()} from the given ${f.collection} indexed by the key returned from [selector] function applied to each ${f.element}. - If any two ${f.element}s would have the same key returned by [selector] the last one gets added to the map. + If any two ${f.element.pluralize()} would have the same key returned by [selector] the last one gets added to the map. """ } returns("Map") @@ -192,8 +192,8 @@ fun snapshots(): List { typeParam("V") doc { f -> """ - Returns Map containing the values provided by [transform] and indexed by [selector] functions applied to ${f.element}s of the given ${f.collection}. - If any two ${f.element}s would have the same key returned by [selector] the last one gets added to the map. + Returns Map containing the values provided by [transform] and indexed by [selector] functions applied to ${f.element.pluralize()} of the given ${f.collection}. + If any two ${f.element.pluralize()} would have the same key returned by [selector] the last one gets added to the map. """ } returns("Map") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/engine/DocExtensions.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/engine/DocExtensions.kt index 00acb6a202b..97c861122c6 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/engine/DocExtensions.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/engine/DocExtensions.kt @@ -27,6 +27,11 @@ object DocExtensions { private fun String.singularize() = removeSuffix("s") + public fun String.pluralize() = when { + this.endsWith("y") -> this.dropLast(1) + "ies" + else -> this + "s" + } + fun String.prefixWithArticle() = (if ("aeiou".any { this.startsWith(it, ignoreCase = true) }) "an " else "a ").concat(this) }