azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Use templating in the docs for generated code to name things properly.

Browse Source
This commit is contained in:
Ilya Gorbunov
2015-10-24 07:22:05 +03:00
parent 5b055ac663
commit b4b84a38d5
14 changed files with 771 additions and 734 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
+26 -26
View File
@@ -1,13 +1,15 @@
package templates
import templates.Family.*
import templates.DocExtensions.element
import templates.DocExtensions.collection
fun aggregates(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
templates add f("all(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns `true` if all elements match the given [predicate]." }
doc { f -> "Returns `true` if all ${f.element}s match the given [predicate]." }
returns("Boolean")
body {
"""
@@ -22,7 +24,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("none(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns `true` if no elements match the given [predicate]." }
doc { f -> "Returns `true` if no ${f.element}s match the given [predicate]." }
returns("Boolean")
body {
"""
@@ -35,7 +37,7 @@ fun aggregates(): List<GenericFunction> {
}
templates add f("none()") {
doc { "Returns `true` if collection has no elements." }
doc { f -> "Returns `true` if the ${f.collection} has no ${f.element}s." }
returns("Boolean")
body {
"""
@@ -50,7 +52,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("any(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns `true` if at least one element matches the given [predicate]." }
doc { f -> "Returns `true` if at least one ${f.element} matches the given [predicate]." }
returns("Boolean")
body {
"""
@@ -63,7 +65,7 @@ fun aggregates(): List<GenericFunction> {
}
templates add f("any()") {
doc { "Returns `true` if collection has at least one element." }
doc { f -> "Returns `true` if ${f.collection} has at least one ${f.element}." }
returns("Boolean")
body {
"""
@@ -78,7 +80,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("count(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns the number of elements matching the given [predicate]." }
doc { f -> "Returns the number of ${f.element}s matching the given [predicate]." }
returns("Int")
body {
"""
@@ -92,7 +94,7 @@ fun aggregates(): List<GenericFunction> {
}
templates add f("count()") {
doc { "Returns the number of elements in this collection." }
doc { f -> "Returns the number of ${f.element}s in this ${f.collection}." }
returns("Int")
body {
"""
@@ -102,7 +104,7 @@ fun aggregates(): List<GenericFunction> {
"""
}
deprecate(Strings) { forBinaryCompatibility }
doc(CharSequences) { "Returns the length of this string."}
doc(CharSequences) { "Returns the length of this char sequence."}
body(CharSequences, Strings) {
"return length()"
}
@@ -115,8 +117,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
include(CharSequences, Strings)
deprecate(Strings) { forBinaryCompatibility }
doc { "Returns the sum of all values produced by [transform] function from elements in the collection." }
doc(CharSequences) { "Returns the sum of all values produced by [transform] function from characters in the string." }
doc { f -> "Returns the sum of all values produced by [transform] function applied to each ${f.element} in the ${f.collection}." }
returns("Int")
body {
"""
@@ -133,8 +134,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
include(CharSequences, Strings)
deprecate(Strings) { forBinaryCompatibility }
doc { "Returns the sum of all values produced by [transform] function from elements in the collection." }
doc(CharSequences) { "Returns the sum of all values produced by [transform] function from characters in the string." }
doc { f -> "Returns the sum of all values produced by [transform] function applied to each ${f.element} in the ${f.collection}." }
returns("Double")
body {
"""
@@ -148,7 +148,7 @@ fun aggregates(): List<GenericFunction> {
}
templates add f("min()") {
doc { "Returns the smallest element or `null` if there are no elements." }
doc { f -> "Returns the smallest ${f.element} or `null` if there are no ${f.element}s." }
returns("T?")
exclude(PrimitiveType.Boolean)
typeParam("T : Comparable<T>")
@@ -182,7 +182,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("minBy(f: (T) -> R)") {
inline(true)
doc { "Returns the first element yielding the smallest value of the given function or `null` if there are no elements." }
doc { f -> "Returns the first ${f.element} yielding the smallest value of the given function or `null` if there are no ${f.element}s." }
typeParam("R : Comparable<R>")
typeParam("T : Any")
returns("T?")
@@ -228,7 +228,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
only(Maps)
doc { "Returns the first element yielding the smallest value of the given function or `null` if there are no elements." }
doc { "Returns the first map entry yielding the smallest value of the given function or `null` if there are no entries." }
typeParam("R : Comparable<R>")
returns("T?")
body {
@@ -252,7 +252,7 @@ fun aggregates(): List<GenericFunction> {
}
templates add f("max()") {
doc { "Returns the largest element or `null` if there are no elements." }
doc { f -> "Returns the largest ${f.element} or `null` if there are no ${f.element}s." }
returns("T?")
exclude(PrimitiveType.Boolean)
typeParam("T : Comparable<T>")
@@ -288,7 +288,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("maxBy(f: (T) -> R)") {
inline(true)
doc { "Returns the first element yielding the largest value of the given function or `null` if there are no elements." }
doc { f -> "Returns the first ${f.element} yielding the largest value of the given function or `null` if there are no ${f.element}s." }
typeParam("R : Comparable<R>")
typeParam("T : Any")
returns("T?")
@@ -334,7 +334,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
only(Maps)
doc { "Returns the first element yielding the largest value of the given function or `null` if there are no elements." }
doc { "Returns the first map entry yielding the largest value of the given function or `null` if there are no entries." }
typeParam("R : Comparable<R>")
returns("T?")
body {
@@ -362,7 +362,7 @@ fun aggregates(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element." }
doc { f -> "Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each ${f.element}." }
typeParam("R")
returns("R")
body {
@@ -379,7 +379,7 @@ fun aggregates(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
only(CharSequences, Strings, Lists, ArraysOfObjects, ArraysOfPrimitives)
doc { "Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value." }
doc { f -> "Accumulates value starting with [initial] value and applying [operation] from right to left to each ${f.element} and current accumulator value." }
typeParam("R")
returns("R")
body {
@@ -401,7 +401,7 @@ fun aggregates(): List<GenericFunction> {
include(CharSequences, Strings)
exclude(ArraysOfObjects, Iterables, Sequences)
doc { "Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element." }
doc { f -> "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}." }
returns("T")
body {
"""
@@ -421,7 +421,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
only(ArraysOfObjects, Iterables, Sequences)
doc { "Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element." }
doc { f -> "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}." }
typeParam("S")
typeParam("T: S")
returns("S")
@@ -444,7 +444,7 @@ fun aggregates(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
only(CharSequences, Strings, ArraysOfPrimitives)
doc { "Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value." }
doc { f -> "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value." }
returns("T")
body {
"""
@@ -465,7 +465,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
only(Lists, ArraysOfObjects)
doc { "Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value." }
doc { f -> "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value." }
typeParam("S")
typeParam("T: S")
returns("S")
@@ -487,7 +487,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("forEach(operation: (T) -> Unit)") {
inline(true)
doc { "Performs the given [operation] on each element." }
doc { f -> "Performs the given [operation] on each ${f.element}." }
returns("Unit")
body {
"""
@@ -502,7 +502,7 @@ fun aggregates(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Performs the given [operation] on each element, providing sequential index with the element." }
doc { f -> "Performs the given [operation] on each ${f.element}, providing sequential index with the ${f.element}." }
returns("Unit")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/DocExtensions.kt
+32
View File
@@ -0,0 +1,32 @@
package templates
import templates.Family.*
object DocExtensions {
val Family.element: String
get() = when (this) {
Strings, CharSequences -> "character"
Maps -> "entry"
else -> "element"
}
val Family.collection: String
get() = when (this) {
CharSequences -> "char sequence"
Strings -> "string"
Sequences -> "sequence"
Maps -> "map"
ArraysOfObjects, ArraysOfPrimitives, InvariantArraysOfObjects -> "array"
else -> "collection"
}
val Family.mapResult: String
get() = when (this) {
Sequences -> "sequence"
else -> "list"
}
fun String.prefixWithArticle() = (if ("aeiou".any { this.startsWith(it, ignoreCase = true) }) "an " else "a ").concat(this)
}
libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt
+39 -53
View File
@@ -1,15 +1,20 @@
package templates
import templates.Family.*
import templates.DocExtensions.element
import templates.DocExtensions.collection
import templates.DocExtensions.prefixWithArticle
fun elements(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
templates add f("contains(element: T)") {
operator(true)
only(Iterables, Sequences, ArraysOfObjects, ArraysOfPrimitives)
doc { "Returns `true` if [element] is found in the collection." }
doc { f -> "Returns `true` if [element] is found in the ${f.collection}." }
customSignature(Iterables, ArraysOfObjects, Sequences) { "contains(element: @kotlin.internal.NoInfer T)" }
returns("Boolean")
body(Iterables) {
@@ -41,9 +46,9 @@ fun elements(): List<GenericFunction> {
templates add f("containsRaw(element: Any?)") {
only(Iterables, Sequences, ArraysOfObjects)
doc {
doc { f ->
"""
Returns `true` if [element] is found in the collection.
Returns `true` if [element] is found in the ${f.collection}.
Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`.
"""
}
@@ -56,7 +61,7 @@ fun elements(): List<GenericFunction> {
templates add f("indexOf(element: T)") {
only(Iterables, Sequences, ArraysOfObjects, ArraysOfPrimitives)
doc { "Returns first index of [element], or -1 if the collection does not contain element." }
doc { f -> "Returns first index of [element], or -1 if the ${f.collection} does not contain element." }
customSignature(Iterables, ArraysOfObjects, Sequences) { "indexOf(element: @kotlin.internal.NoInfer T)" }
returns("Int")
body { f ->
@@ -116,9 +121,9 @@ fun elements(): List<GenericFunction> {
templates add f("indexOfRaw(element: Any?)") {
only(Iterables, Sequences, ArraysOfObjects, Lists)
doc {
doc { f ->
"""
Returns first index of [element], or -1 if the collection does not contain element.
Returns first index of [element], or -1 if the ${f.collection} does not contain element.
Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`.
"""
}
@@ -132,7 +137,7 @@ fun elements(): List<GenericFunction> {
templates add f("lastIndexOf(element: T)") {
only(Iterables, Sequences, ArraysOfObjects, ArraysOfPrimitives)
doc { "Returns last index of [element], or -1 if the collection does not contain element." }
doc { f -> "Returns last index of [element], or -1 if the ${f.collection} does not contain element." }
customSignature(Iterables, ArraysOfObjects, Sequences) { "lastIndexOf(element: @kotlin.internal.NoInfer T)" }
returns("Int")
body { f ->
@@ -193,9 +198,9 @@ fun elements(): List<GenericFunction> {
templates add f("lastIndexOfRaw(element: Any?)") {
only(Iterables, Sequences, ArraysOfObjects, Lists)
doc {
doc { f ->
"""
Returns last index of [element], or -1 if the collection does not contain element.
Returns last index of [element], or -1 if the ${f.collection} does not contain element.
Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`.
"""
}
@@ -210,7 +215,7 @@ fun elements(): List<GenericFunction> {
templates add f("indexOfFirst(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns index of the first element matching the given [predicate], or -1 if the collection does not contain such element." }
doc { f -> "Returns index of the first ${f.element} matching the given [predicate], or -1 if the ${f.collection} does not contain such ${f.element}." }
returns("Int")
body {
"""
@@ -240,7 +245,7 @@ fun elements(): List<GenericFunction> {
templates add f("indexOfLast(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns index of the last element matching the given [predicate], or -1 if the collection does not contain such element." }
doc { f -> "Returns index of the last ${f.element} matching the given [predicate], or -1 if the ${f.collection} does not contain such ${f.element}." }
returns("Int")
body {
"""
@@ -270,7 +275,7 @@ fun elements(): List<GenericFunction> {
templates add f("elementAt(index: Int)") {
val index = '$' + "index"
doc { "Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this collection." }
doc { f -> "Returns ${f.element.prefixWithArticle()} at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this ${f.collection}." }
returns("T")
body {
"""
@@ -294,7 +299,7 @@ fun elements(): List<GenericFunction> {
}
templates add f("elementAtOrElse(index: Int, defaultValue: (Int) -> T)") {
doc { "Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this collection." }
doc { f -> "Returns ${f.element.prefixWithArticle()} at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this ${f.collection}." }
returns("T")
body {
"""
@@ -336,7 +341,7 @@ fun elements(): List<GenericFunction> {
}
templates add f("getOrElse(index: Int, defaultValue: (Int) -> T)") {
doc { "Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this collection." }
doc { f -> "Returns ${f.element.prefixWithArticle()} at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this ${f.collection}." }
returns("T")
inline(true)
deprecate(Strings) { forBinaryCompatibility }
@@ -350,7 +355,7 @@ fun elements(): List<GenericFunction> {
templates add f("elementAtOrNull(index: Int)") {
doc { "Returns an element at the given [index] or `null` if the [index] is out of bounds of this collection." }
doc { f -> "Returns ${f.element.prefixWithArticle()} at the given [index] or `null` if the [index] is out of bounds of this ${f.collection}." }
returns("T?")
body {
"""
@@ -391,7 +396,7 @@ fun elements(): List<GenericFunction> {
}
templates add f("getOrNull(index: Int)") {
doc { "Returns an element at the given [index] or `null` if the [index] is out of bounds of this collection." }
doc { f -> "Returns ${f.element.prefixWithArticle()} at the given [index] or `null` if the [index] is out of bounds of this ${f.collection}." }
returns("T?")
deprecate(Strings) { forBinaryCompatibility }
only(CharSequences, Strings, Lists, ArraysOfObjects, ArraysOfPrimitives)
@@ -404,11 +409,8 @@ fun elements(): List<GenericFunction> {
templates add f("first()") {
doc { """Returns first element.
@throws [NoSuchElementException] if the collection is empty.
""" }
doc(CharSequences) { """Returns first character.
@throws [NoSuchElementException] if the CharSequence is empty.
doc { f -> """Returns first ${f.element}.
@throws [NoSuchElementException] if the ${f.collection} is empty.
""" }
returns("T")
body {
@@ -447,8 +449,7 @@ fun elements(): List<GenericFunction> {
}
}
templates add f("firstOrNull()") {
doc { "Returns the first element, or `null` if the collection is empty." }
doc(CharSequences) { "Returns the first character, or `null` if CharSequence is empty." }
doc { f -> "Returns the first ${f.element}, or `null` if the ${f.collection} is empty." }
returns("T?")
body {
"""
@@ -489,10 +490,8 @@ fun elements(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { """Returns the first element matching the given [predicate].
@throws [NoSuchElementException] if no such element is found.""" }
doc(CharSequences) { """Returns the first character matching the given [predicate].
@throws [NoSuchElementException] if no such character is found.""" }
doc { f -> """Returns the first ${f.element} matching the given [predicate].
@throws [NoSuchElementException] if no such ${f.element} is found.""" }
returns("T")
body {
"""
@@ -507,8 +506,7 @@ fun elements(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns the first element matching the given [predicate], or `null` if element was not found." }
doc(CharSequences) { "Returns the first character matching the given [predicate], or `null` if character was not found." }
doc { f -> "Returns the first ${f.element} matching the given [predicate], or `null` if ${f.element} was not found." }
returns("T?")
body {
"""
@@ -522,17 +520,14 @@ fun elements(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns the first element matching the given [predicate], or `null` if element was not found." }
doc(CharSequences) { "Returns the first character matching the given [predicate], or `null` if character was not found." }
doc { f -> "Returns the first ${f.element} matching the given [predicate], or `null` if no such ${f.element} was found." }
returns("T?")
body { "return firstOrNull(predicate)"}
}
templates add f("last()") {
doc { """Returns the last element.
@throws [NoSuchElementException] if the collection is empty.""" }
doc(CharSequences) { """"Returns the last character.
@throws [NoSuchElementException] if the string is empty.""" }
doc { f -> """Returns the last ${f.element}.
@throws [NoSuchElementException] if the ${f.collection} is empty.""" }
returns("T")
body {
"""
@@ -577,8 +572,7 @@ fun elements(): List<GenericFunction> {
}
templates add f("lastOrNull()") {
doc { "Returns the last element, or `null` if the collection is empty." }
doc(CharSequences) { "Returns the last character, or `null` if the string is empty." }
doc { f -> "Returns the last ${f.element}, or `null` if the ${f.collection} is empty." }
returns("T?")
body {
"""
@@ -625,10 +619,8 @@ fun elements(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { """Returns the last element matching the given [predicate].
@throws [NoSuchElementException] if no such element is found.""" }
doc(CharSequences) { """"Returns the last character matching the given [predicate].
@throws [NoSuchElementException] if no such character is found.""" }
doc { f -> """Returns the last ${f.element} matching the given [predicate].
@throws [NoSuchElementException] if no such ${f.element} is found.""" }
returns("T")
body { f ->
(if (f == Iterables)
@@ -666,8 +658,7 @@ fun elements(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns the last element matching the given [predicate], or `null` if no such element was found." }
doc(CharSequences) { "Returns the last character matching the given [predicate], or `null` if no such character was found." }
doc { f -> "Returns the last ${f.element} matching the given [predicate], or `null` if no such ${f.element} was found." }
returns("T?")
body { f ->
(if (f == Iterables)
@@ -702,15 +693,13 @@ fun elements(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(Lists, CharSequences, Strings)
doc { "Returns the last element matching the given [predicate], or `null` if no such element was found." }
doc(CharSequences) { "Returns the last character matching the given [predicate], or `null` if no such character was found." }
doc { f -> "Returns the last ${f.element} matching the given [predicate], or `null` if no such ${f.element} was found." }
returns("T?")
body { "return lastOrNull(predicate)"}
}
templates add f("single()") {
doc { "Returns the single element, or throws an exception if the collection is empty or has more than one element." }
doc(CharSequences) { "Returns the single character, or throws an exception if the string is empty or has more than one character." }
doc { f -> "Returns the single ${f.element}, or throws an exception if the ${f.collection} is empty or has more than one ${f.element}." }
returns("T")
body {
"""
@@ -765,8 +754,7 @@ fun elements(): List<GenericFunction> {
}
templates add f("singleOrNull()") {
doc { "Returns single element, or `null` if the collection is empty or has more than one element." }
doc(CharSequences) { "Returns the single character, or `null` if the string is empty or has more than one character." }
doc { f -> "Returns single ${f.element}, or `null` if the ${f.collection} is empty or has more than one ${f.element}." }
returns("T?")
body {
"""
@@ -812,8 +800,7 @@ fun elements(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element." }
doc(CharSequences) { "Returns the single character matching the given [predicate], or throws exception if there is no or more than one matching character." }
doc { f -> "Returns the single ${f.element} matching the given [predicate], or throws exception if there is no or more than one matching ${f.element}." }
returns("T")
body {
"""
@@ -836,8 +823,7 @@ fun elements(): List<GenericFunction> {
inline(true)
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found." }
doc(CharSequences) { "Returns the single character matching the given [predicate], or `null` if character was not found or more than one character was found." }
doc { f -> "Returns the single ${f.element} matching the given [predicate], or `null` if ${f.element} was not found or more than one ${f.element} was found." }
returns("T?")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
+9 -8
View File
@@ -1,6 +1,7 @@
package templates
import templates.Family.*
import templates.DocExtensions.collection
fun generators(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
@@ -395,11 +396,11 @@ fun generators(): List<GenericFunction> {
templates add f("partition(predicate: (T) -> Boolean)") {
inline(true)
doc {
doc { f ->
"""
Splits the original collection into pair of collections,
where *first* collection contains elements for which [predicate] yielded `true`,
while *second* collection contains elements for which [predicate] yielded `false`.
Splits the original ${f.collection} into pair of lists,
where *first* list contains elements for which [predicate] yielded `true`,
while *second* list contains elements for which [predicate] yielded `false`.
"""
}
// TODO: Sequence variant
@@ -422,7 +423,7 @@ fun generators(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
doc(CharSequences) {
"""
Splits the original string into pair of strings,
Splits the original char sequence into pair of strings,
where *first* string contains characters for which [predicate] yielded `true`,
while *second* string contains characters for which [predicate] yielded `false`.
"""
@@ -560,7 +561,7 @@ fun generators(): List<GenericFunction> {
only(CharSequences, Strings)
doc {
"""
Returns a list of values built from characters of both strings with same indexes using provided [transform]. List has length of shortest string.
Returns a list of values built from characters of both char sequences with same indexes using provided [transform]. List has length of shortest char sequence.
"""
}
typeParam("V")
@@ -601,7 +602,7 @@ fun generators(): List<GenericFunction> {
only(CharSequences, Strings)
doc {
"""
Returns a list of pairs built from characters of both strings with same indexes. List has length of shortest collection.
Returns a list of pairs built from characters of both char sequences with same indexes. List has length of shortest char sequence.
"""
}
returns("List<Pair<Char, Char>>")
@@ -648,7 +649,7 @@ fun generators(): List<GenericFunction> {
doc {
"""
Returns a sequence of pairs built from elements of both collections with same indexes.
Resulting sequence has length of shortest input sequences.
Resulting sequence has length of shortest input sequence.
"""
}
typeParam("R")
libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
+15 -16
View File
@@ -1,6 +1,9 @@
package templates
import templates.Family.*
import templates.DocExtensions.element
import templates.DocExtensions.collection
import templates.DocExtensions.mapResult
fun mapping(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
@@ -8,7 +11,7 @@ fun mapping(): List<GenericFunction> {
templates add f("withIndex()") {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns a lazy [Iterable] of [IndexedValue] for each element of the original collection." }
doc { f -> "Returns a ${if (f == Sequences) f.mapResult else "lazy [Iterable]"} of [IndexedValue] for each ${f.element} of the original ${f.collection}." }
returns("Iterable<IndexedValue<T>>")
body {
"""
@@ -17,7 +20,6 @@ fun mapping(): List<GenericFunction> {
}
returns(Sequences) { "Sequence<IndexedValue<T>>" }
doc(Sequences) { "Returns a sequence of [IndexedValue] for each element of the original sequence." }
body(Sequences) {
"""
return IndexingSequence(this)
@@ -28,7 +30,7 @@ fun mapping(): List<GenericFunction> {
templates add f("mapIndexed(transform: (Int, T) -> R)") {
inline(true)
doc { "Returns a list containing the results of applying the given [transform] function to each element and its index of the original collection." }
doc { f -> "Returns a ${f.mapResult} containing the results of applying the given [transform] function to each ${f.element} and its index in the original ${f.collection}." }
typeParam("R")
returns("List<R>")
body {
@@ -43,7 +45,6 @@ fun mapping(): List<GenericFunction> {
}
inline(false, Sequences)
returns(Sequences) { "Sequence<R>" }
doc(Sequences) { "Returns a sequence containing the results of applying the given [transform] function to each element and its index of the original sequence." }
body(Sequences) {
"return TransformingIndexedSequence(this, transform)"
}
@@ -52,7 +53,7 @@ fun mapping(): List<GenericFunction> {
templates add f("map(transform: (T) -> R)") {
inline(true)
doc { "Returns a list containing the results of applying the given [transform] function to each element of the original collection." }
doc { f -> "Returns a ${f.mapResult} containing the results of applying the given [transform] function to each ${f.element} of the original ${f.collection}." }
typeParam("R")
returns("List<R>")
body {
@@ -68,7 +69,6 @@ fun mapping(): List<GenericFunction> {
inline(false, Sequences)
returns(Sequences) { "Sequence<R>" }
doc(Sequences) { "Returns a sequence containing the results of applying the given [transform] function to each element of the original sequence." }
body(Sequences) {
"return TransformingSequence(this, transform)"
}
@@ -79,7 +79,7 @@ fun mapping(): List<GenericFunction> {
templates add f("mapNotNull(transform: (T) -> R)") {
inline(true)
exclude(Strings, ArraysOfPrimitives)
doc { "Returns a list containing the results of applying the given [transform] function to each non-null element of the original collection." }
doc { f -> "Returns a ${f.mapResult} containing the results of applying the given [transform] function to each non-null ${f.element} of the original ${f.collection}." }
deprecate(Deprecation("This function will change its semantics soon to map&filter rather than filter&map. Use filterNotNull().map {} instead.", replaceWith = "filterNotNull().map(transform)"))
typeParam("T : Any")
typeParam("R")
@@ -91,7 +91,6 @@ fun mapping(): List<GenericFunction> {
"""
}
doc(Sequences) { "Returns a sequence containing the results of applying the given [transform] function to each non-null element of the original sequence." }
returns(Sequences) { "Sequence<R>" }
inline(false, Sequences)
body(Sequences) {
@@ -105,9 +104,9 @@ fun mapping(): List<GenericFunction> {
templates add f("mapTo(destination: C, transform: (T) -> R)") {
inline(true)
doc {
doc { f ->
"""
Appends transformed elements of the original collection using the given [transform] function
Appends transformed ${f.element}s of the original ${f.collection} using the given [transform] function
to the given [destination].
"""
}
@@ -129,9 +128,9 @@ fun mapping(): List<GenericFunction> {
templates add f("mapIndexedTo(destination: C, transform: (Int, T) -> R)") {
inline(true)
doc {
doc { f ->
"""
Appends transformed elements and their indices of the original collection using the given [transform] function
Appends transformed ${f.element}s and their indices in the original ${f.collection} using the given [transform] function
to the given [destination].
"""
}
@@ -185,7 +184,7 @@ fun mapping(): List<GenericFunction> {
inline(true)
exclude(Sequences)
doc { "Returns a single list of all elements yielded from results of [transform] function being invoked on each element of original collection." }
doc { f -> "Returns a single list of all elements yielded from results of [transform] function being invoked on each ${f.element} of original ${f.collection}." }
typeParam("R")
returns("List<R>")
body {
@@ -208,7 +207,7 @@ fun mapping(): List<GenericFunction> {
templates add f("flatMapTo(destination: C, transform: (T) -> Iterable<R>)") {
inline(true)
exclude(Sequences)
doc { "Appends all elements yielded from results of [transform] function being invoked on each element of original collection, to the given [destination]." }
doc { f -> "Appends all elements yielded from results of [transform] function being invoked on each ${f.element} of original ${f.collection}, to the given [destination]." }
typeParam("R")
typeParam("C : MutableCollection<in R>")
returns("C")
@@ -249,7 +248,7 @@ fun mapping(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns a map of the elements in original collection grouped by the result of given [toKey] function." }
doc { f -> "Returns a map of the ${f.element}s in original ${f.collection} grouped by the result of given [toKey] function." }
typeParam("K")
returns("Map<K, List<T>>")
body { "return groupByTo(LinkedHashMap<K, MutableList<T>>(), toKey)" }
@@ -261,7 +260,7 @@ fun mapping(): List<GenericFunction> {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
typeParam("K")
doc { "Appends elements from original collection grouped by the result of given [toKey] function to the given [map]." }
doc { f -> "Appends ${f.element}s from original ${f.collection} grouped by the result of given [toKey] function to the given [map]." }
returns("Map<K, MutableList<T>>")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Numeric.kt
+3 -2
View File
@@ -1,6 +1,7 @@
package templates
import templates.Family.*
import templates.DocExtensions.collection
fun numeric(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
@@ -8,7 +9,7 @@ fun numeric(): List<GenericFunction> {
templates add f("sum()") {
exclude(Strings)
buildFamilies.forEach { family -> onlyPrimitives(family, numericPrimitives) }
doc { "Returns the sum of all elements in the collection." }
doc { f -> "Returns the sum of all elements in the ${f.collection}." }
returns("SUM")
platformName("sumOf<T>")
body {
@@ -26,7 +27,7 @@ fun numeric(): List<GenericFunction> {
templates add f("average()") {
exclude(Strings)
buildFamilies.forEach { family -> onlyPrimitives(family, numericPrimitives) }
doc { "Returns an average value of elements in the collection."}
doc { f -> "Returns an average value of elements in the ${f.collection}."}
returns("Double")
platformName("averageOf<T>")
body {
libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt
+16 -13
View File
@@ -1,13 +1,16 @@
package templates
import templates.Family.*
import templates.DocExtensions.element
import templates.DocExtensions.collection
import templates.DocExtensions.mapResult
fun sets(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
templates add f("toMutableSet()") {
exclude(Strings)
doc { "Returns a mutable set containing all distinct elements from the given collection." }
doc { f -> "Returns a mutable set containing all distinct ${f.element}s from the given ${f.collection}." }
returns("MutableSet<T>")
body {
"""
@@ -36,28 +39,29 @@ fun sets(): List<GenericFunction> {
templates add f("distinct()") {
exclude(Strings)
val collectionDoc = """
Returns a list containing only distinct elements from the given collection.
The elements in the resulting list are in the same order as they were in the source collection.
doc { f ->
"""
doc { collectionDoc }
Returns a ${f.mapResult} containing only distinct ${f.element}s 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}.
"""
}
returns("List<T>")
body { "return this.toMutableSet().toList()" }
doc(Sequences) { collectionDoc.replace("list", "sequence").replace("collection", "sequence") }
returns(Sequences) { "Sequence<T>" }
body(Sequences) { "return this.distinctBy { it }" }
}
templates add f("distinctBy(keySelector: (T) -> K)") {
exclude(Strings)
val collectionDoc = """
Returns a list containing only distinct elements from the given collection according to the [keySelector].
The elements in the resulting list are in the same order as they were in the source collection.
doc { f ->
"""
doc { collectionDoc }
Returns a ${f.mapResult} containing only distinct ${f.element}s from the given ${f.collection} according to the [keySelector].
The ${f.element}s in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}.
"""
}
inline(true)
typeParam("K")
@@ -76,7 +80,6 @@ fun sets(): List<GenericFunction> {
}
inline(false, Sequences)
doc(Sequences) { collectionDoc.replace("list", "sequence").replace("collection", "sequence") }
returns(Sequences) { "Sequence<T>" }
body(Sequences) {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt
+15 -13
View File
@@ -1,7 +1,8 @@
package templates
import templates.Family.*
import java.util.ArrayList
import templates.DocExtensions.element
import templates.DocExtensions.collection
fun snapshots(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
@@ -9,7 +10,7 @@ fun snapshots(): List<GenericFunction> {
templates add f("toCollection(collection: C)") {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Appends all elements to the given [collection]." }
doc { f -> "Appends all ${f.element}s to the given [collection]." }
returns("C")
typeParam("C : MutableCollection<in T>")
body {
@@ -23,7 +24,7 @@ fun snapshots(): List<GenericFunction> {
}
templates add f("toSet()") {
doc { "Returns a [Set] of all elements." }
doc { f -> "Returns a [Set] of all ${f.element}s." }
returns("Set<T>")
body { "return toCollection(LinkedHashSet<T>(mapCapacity(collectionSizeOrDefault(12))))" }
body(Sequences) { "return toCollection(LinkedHashSet<T>())" }
@@ -33,7 +34,7 @@ fun snapshots(): List<GenericFunction> {
}
templates add f("toHashSet()") {
doc { "Returns a [HashSet] of all elements." }
doc { f -> "Returns a [HashSet] of all ${f.element}s." }
returns("HashSet<T>")
body { "return toCollection(HashSet<T>(mapCapacity(collectionSizeOrDefault(12))))" }
body(Sequences) { "return toCollection(HashSet<T>())" }
@@ -45,13 +46,13 @@ fun snapshots(): List<GenericFunction> {
templates add f("toSortedSet()") {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns a [SortedSet] of all elements." }
doc { f -> "Returns a [SortedSet] of all ${f.element}s." }
returns("SortedSet<T>")
body { "return toCollection(TreeSet<T>())" }
}
templates add f("toArrayList()") {
doc { "Returns an [ArrayList] of all elements." }
doc { f -> "Returns an [ArrayList] of all ${f.element}s." }
returns("ArrayList<T>")
body { "return toCollection(ArrayList<T>())" }
body(Iterables) {
@@ -91,7 +92,7 @@ fun snapshots(): List<GenericFunction> {
templates add f("toList()") {
deprecate(Strings) { forBinaryCompatibility }
include(CharSequences, Strings)
doc { "Returns a [List] containing all elements." }
doc { f -> "Returns a [List] containing all ${f.element}s." }
returns("List<T>")
body { "return this.toArrayList()" }
}
@@ -116,10 +117,11 @@ fun snapshots(): List<GenericFunction> {
templates add f("toMapBy(selector: (T) -> K)") {
inline(true)
typeParam("K")
doc {
doc { f ->
"""
Returns Map containing the values from the given collection indexed by [selector].
If any two elements would have the same key returned by [selector] the last one gets added to the map.
Returns Map containing the ${f.element}s 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.
"""
}
returns("Map<K, T>")
@@ -175,10 +177,10 @@ fun snapshots(): List<GenericFunction> {
inline(true)
typeParam("K")
typeParam("V")
doc {
doc { f ->
"""
Returns Map containing the values provided by [transform] and indexed by [selector] from the given collection.
If any two elements 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}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<K, V>")