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

Standard library documentation updates.

Browse Source
This commit is contained in:
Dmitry Jemerov
2015-02-04 13:53:42 +01:00
parent 6763d61aae
commit 7827bbf64b
41 changed files with 1144 additions and 625 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
+6 -4
View File
@@ -47,7 +47,7 @@ fun aggregates(): List<GenericFunction> {
templates add f("any(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns *true* if any element matches the given *predicate*" }
doc { "Returns *true* if any element matches the given [predicate]" }
returns("Boolean")
body {
"""
@@ -73,7 +73,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 { "Returns the number of elements matching the given [predicate]" }
returns("Int")
body {
"""
@@ -105,7 +105,8 @@ fun aggregates(): List<GenericFunction> {
templates add f("sumBy(transform: (T) -> Int)") {
inline(true)
doc { "Returns the sum of all values produced by `transform` function from elements in the collection" }
doc { "Returns the sum of all values produced by [transform] function from elements in the collection" }
doc(Strings) { "Returns the sum of all values produced by [transform] function from characters in the string" }
returns("Int")
body {
"""
@@ -120,7 +121,8 @@ fun aggregates(): List<GenericFunction> {
templates add f("sumByDouble(transform: (T) -> Double)") {
inline(true)
doc { "Returns the sum of all values produced by `transform` function from elements in the collection" }
doc { "Returns the sum of all values produced by [transform] function from elements in the collection" }
doc(Strings) { "Returns the sum of all values produced by [transform] function from characters in the string" }
returns("Double")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt
+35 -13
View File
@@ -25,7 +25,7 @@ fun elements(): List<GenericFunction> {
templates add f("indexOf(element: T)") {
exclude(Strings)
doc { "Returns first index of *element*, or -1 if the collection does not contain element" }
doc { "Returns first index of [element], or -1 if the collection does not contain element" }
returns("Int")
body {
"""
@@ -153,7 +153,12 @@ fun elements(): List<GenericFunction> {
}
templates add f("first()") {
doc { "Returns first element" }
doc { """Returns first element.
@throws NoSuchElementException if the collection is empty.
""" }
doc(Strings) { """Returns first character.
@throws NoSuchElementException if the string is empty.
""" }
returns("T")
body {
"""
@@ -182,7 +187,8 @@ fun elements(): List<GenericFunction> {
}
}
templates add f("firstOrNull()") {
doc { "Returns first element, or null if collection is empty" }
doc { "Returns the first element, or null if the collection is empty." }
doc(Strings) { "Returns the first character, or null if string is empty." }
returns("T?")
body {
"""
@@ -212,7 +218,10 @@ fun elements(): List<GenericFunction> {
templates add f("first(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns first element matching the given *predicate*" }
doc { """"Returns the first element matching the given [predicate].
@throws NoSuchElementException if no such element is found.""" }
doc(Strings) { """Returns the first character matching the given [predicate].
@throws NoSuchElementException if no such character is found.""" }
returns("T")
body {
"""
@@ -225,7 +234,8 @@ fun elements(): List<GenericFunction> {
templates add f("firstOrNull(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns first element matching the given *predicate*, or *null* if element was not found" }
doc { "Returns first element matching the given [predicate], or `null` if element was not found" }
doc(Strings) { "Returns first character matching the given [predicate], or `null` if character was not found" }
returns("T?")
body {
"""
@@ -236,7 +246,10 @@ fun elements(): List<GenericFunction> {
}
templates add f("last()") {
doc { "Returns last element" }
doc { """Returns the last element.
@throws NoSuchElementException if the collection is empty.""" }
doc(Strings) { """"Returns the last character.
@throws NoSuchElementException if the string is empty.""" }
returns("T")
body {
"""
@@ -280,7 +293,8 @@ fun elements(): List<GenericFunction> {
}
templates add f("lastOrNull()") {
doc { "Returns last element, or null if collection is empty" }
doc { "Returns the last element, or `null` if the collection is empty" }
doc(Strings) { "Returns the last character, or `null` if the string is empty" }
returns("T?")
body {
"""
@@ -323,7 +337,10 @@ fun elements(): List<GenericFunction> {
templates add f("last(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns last element matching the given *predicate*" }
doc { """Returns the last element matching the given [predicate].
@throws NoSuchElementException if no such element is found.""" }
doc(Strings) { """"Returns the last character matching the given [predicate].
@throws NoSuchElementException if no such character is found.""" }
returns("T")
body {
"""
@@ -343,7 +360,8 @@ fun elements(): List<GenericFunction> {
templates add f("lastOrNull(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns last element matching the given *predicate*, or null if element was not found" }
doc { "Returns the last element matching the given [predicate], or `null` if no such element was found." }
doc(Strings) { "Returns the last character matching the given [predicate], or `null` if no such character was found." }
returns("T?")
body {
"""
@@ -359,7 +377,8 @@ fun elements(): List<GenericFunction> {
}
templates add f("single()") {
doc { "Returns single element, or throws exception if there is no or more than one element" }
doc { "Returns the single element, or throws an exception if the collection is empty or has more than one element." }
doc(Strings) { "Returns the single character, or throws an exception if the string is empty or has more than one character." }
returns("T")
body {
"""
@@ -402,7 +421,8 @@ fun elements(): List<GenericFunction> {
}
templates add f("singleOrNull()") {
doc { "Returns single element, or null if collection is empty, or throws exception if there is more than one element" }
doc { "Returns single element, or `null` if the collection is empty or has more than one element." }
doc(Strings) { "Returns the single character, or `null` if the string is empty or has more than one character." }
returns("T?")
body {
"""
@@ -434,7 +454,8 @@ fun elements(): List<GenericFunction> {
templates add f("single(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns single element matching the given *predicate*, or throws exception if there is no or more than one element" }
doc { "Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element" }
doc(Strings) { "Returns the single character matching the given [predicate], or throws exception if there is no or more than one matching character" }
returns("T")
body {
"""
@@ -455,7 +476,8 @@ fun elements(): List<GenericFunction> {
templates add f("singleOrNull(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found" }
doc { "Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found" }
doc(Strings) { "Returns the single character matching the given [predicate], or `null` if character was not found or more than one character was found" }
returns("T?")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt
+23 -16
View File
@@ -6,7 +6,7 @@ fun filtering(): List<GenericFunction> {
val templates = arrayListOf<GenericFunction>()
templates add f("drop(n: Int)") {
doc { "Returns a list containing all elements except first *n* elements" }
doc { "Returns a list containing all elements except first [n] elements" }
returns("List<T>")
body {
"""
@@ -19,7 +19,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Streams) { "Returns a stream containing all elements except first *n* elements" }
doc(Streams) { "Returns a stream containing all elements except first [n] elements" }
returns(Streams) { "Stream<T>" }
body(Streams) {
"""
@@ -27,6 +27,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string with the first [n] characters removed"}
body(Strings) { "return substring(Math.min(n, length()))" }
returns(Strings) { "String" }
@@ -46,7 +47,7 @@ fun filtering(): List<GenericFunction> {
}
templates add f("take(n: Int)") {
doc { "Returns a list containing first *n* elements" }
doc { "Returns a list containing first [n] elements" }
returns("List<T>")
body {
"""
@@ -61,6 +62,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing the first [n] characters from this string, or the entire string if this string is shorter"}
body(Strings) { "return substring(0, Math.min(n, length()))" }
returns(Strings) { "String" }
@@ -91,7 +93,7 @@ fun filtering(): List<GenericFunction> {
templates add f("dropWhile(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns a list containing all elements except first elements that satisfy the given *predicate*" }
doc { "Returns a list containing all elements except first elements that satisfy the given [predicate]" }
returns("List<T>")
body {
"""
@@ -108,6 +110,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing all characters except first characters that satisfy the given [predicate]" }
returns(Strings) { "String" }
body(Strings) {
"""
@@ -120,7 +123,7 @@ fun filtering(): List<GenericFunction> {
}
inline(false, Streams)
doc(Streams) { "Returns a stream containing all elements except first elements that satisfy the given *predicate*" }
doc(Streams) { "Returns a stream containing all elements except first elements that satisfy the given [predicate]" }
returns(Streams) { "Stream<T>" }
body(Streams) {
"""
@@ -133,7 +136,7 @@ fun filtering(): List<GenericFunction> {
templates add f("takeWhile(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns a list containing first elements satisfying the given *predicate*" }
doc { "Returns a list containing first elements satisfying the given [predicate]" }
returns("List<T>")
body {
"""
@@ -147,6 +150,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing the first characters that satisfy the given [predicate]"}
returns(Strings) { "String" }
body(Strings) {
"""
@@ -159,7 +163,7 @@ fun filtering(): List<GenericFunction> {
}
inline(false, Streams)
doc(Streams) { "Returns a stream containing first elements satisfying the given *predicate*" }
doc(Streams) { "Returns a stream containing first elements satisfying the given [predicate]" }
returns(Streams) { "Stream<T>" }
body(Streams) {
"""
@@ -171,7 +175,7 @@ fun filtering(): List<GenericFunction> {
templates add f("filter(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns a list containing all elements matching the given *predicate*" }
doc { "Returns a list containing all elements matching the given [predicate]" }
returns("List<T>")
body {
"""
@@ -179,6 +183,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing only those characters from the original string that match the given [predicate]" }
returns(Strings) { "String" }
body(Strings) {
"""
@@ -187,7 +192,7 @@ fun filtering(): List<GenericFunction> {
}
inline(false, Streams)
doc(Streams) { "Returns a stream containing all elements matching the given *predicate*" }
doc(Streams) { "Returns a stream containing all elements matching the given [predicate]" }
returns(Streams) { "Stream<T>" }
body(Streams) {
"""
@@ -199,7 +204,7 @@ fun filtering(): List<GenericFunction> {
templates add f("filterTo(destination: C, predicate: (T) -> Boolean)") {
inline(true)
doc { "Appends all elements matching the given *predicate* into the given *destination*" }
doc { "Appends all elements matching the given [predicate] into the given [destination]" }
typeParam("C : TCollection")
returns("C")
@@ -210,7 +215,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Appends all characters matching the given *predicate* to the given *destination*" }
doc(Strings) { "Appends all characters matching the given [predicate] to the given [destination]" }
body(Strings) {
"""
for (index in 0..length - 1) {
@@ -225,7 +230,7 @@ fun filtering(): List<GenericFunction> {
templates add f("filterNot(predicate: (T) -> Boolean)") {
inline(true)
doc { "Returns a list containing all elements not matching the given *predicate*" }
doc { "Returns a list containing all elements not matching the given [predicate]" }
returns("List<T>")
body {
"""
@@ -233,6 +238,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing only those characters from the original string that do not match the given [predicate]" }
returns(Strings) { "String" }
body(Strings) {
"""
@@ -241,7 +247,7 @@ fun filtering(): List<GenericFunction> {
}
inline(false, Streams)
doc(Streams) { "Returns a stream containing all elements not matching the given *predicate*" }
doc(Streams) { "Returns a stream containing all elements not matching the given [predicate]" }
returns(Streams) { "Stream<T>" }
body(Streams) {
"""
@@ -253,7 +259,7 @@ fun filtering(): List<GenericFunction> {
templates add f("filterNotTo(destination: C, predicate: (T) -> Boolean)") {
inline(true)
doc { "Appends all elements not matching the given *predicate* to the given *destination*" }
doc { "Appends all elements not matching the given [predicate] to the given [destination]" }
typeParam("C : TCollection")
returns("C")
@@ -264,7 +270,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Appends all characters not matching the given *predicate* to the given *destination*" }
doc(Strings) { "Appends all characters not matching the given [predicate] to the given [destination]" }
body(Strings) {
"""
for (element in this) if (!predicate(element)) destination.append(element)
@@ -296,7 +302,7 @@ fun filtering(): List<GenericFunction> {
templates add f("filterNotNullTo(destination: C)") {
exclude(ArraysOfPrimitives, Strings)
doc { "Appends all elements that are not null to the given *destination*" }
doc { "Appends all elements that are not null to the given [destination]" }
returns("C")
typeParam("C : TCollection")
typeParam("T : Any")
@@ -323,6 +329,7 @@ fun filtering(): List<GenericFunction> {
"""
}
doc(Strings) { "Returns a string containing characters at specified positions" }
returns(Strings) { "String" }
body(Strings) {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt
+6 -6
View File
@@ -8,10 +8,10 @@ fun strings(): List<GenericFunction> {
templates add f("joinTo(buffer: A, separator: String = \", \", prefix: String = \"\", postfix: String = \"\", limit: Int = -1, truncated: String = \"...\")") {
doc {
"""
Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied
Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied.
If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will
a special *truncated* separator (which defaults to "...")
If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
elements will be appended, followed by the [truncated] string (which defaults to "...").
"""
}
typeParam("A : Appendable")
@@ -54,10 +54,10 @@ fun strings(): List<GenericFunction> {
templates add f("joinToString(separator: String = \", \", prefix: String = \"\", postfix: String = \"\", limit: Int = -1, truncated: String = \"...\")") {
doc {
"""
Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied.
Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied.
If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will
a special *truncated* separator (which defaults to "..."
If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
elements will be appended, followed by the [truncated] string (which defaults to "...").
"""
}