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

More standard library documentation.

Browse Source
This commit is contained in:
Dmitry Jemerov
2015-03-05 19:07:02 +01:00
parent cb27797845
commit 32072d0a4f
44 changed files with 1702 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
generators/src/org/jetbrains/kotlin/generators/builtins/arrays.kt
+1 -1
View File
@@ -29,7 +29,7 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
val s = kind.capitalized
val defaultValue = when(kind) { PrimitiveType.BOOLEAN -> "false"; else -> "zero" }
out.println("/**")
out.println(" * An array of ${typeLower}s. When targeting the JVM, instances of this class are represented as ${typeLower}[].")
out.println(" * An array of ${typeLower}s. When targeting the JVM, instances of this class are represented as `${typeLower}[]`.")
out.println(" * @constructor Creates a new array of the specified [size], with all elements initialized to ${defaultValue}.")
out.println(" */")
out.println("public class ${s}Array(size: Int) : Cloneable {")
generators/src/org/jetbrains/kotlin/generators/builtins/functions.kt
+19 -5
View File
@@ -24,14 +24,15 @@ val MAX_PARAM_COUNT = 22
enum class FunctionKind(
private val classNamePrefix: String,
val docPrefix: String?,
val hasReceiverParameter: Boolean,
private val superClassNamePrefix: String?
) {
FUNCTION : FunctionKind("Function", false, null)
EXTENSION_FUNCTION : FunctionKind("ExtensionFunction", true, null)
K_FUNCTION : FunctionKind("KFunction", false, "Function")
K_MEMBER_FUNCTION : FunctionKind("KMemberFunction", true, "ExtensionFunction")
K_EXTENSION_FUNCTION : FunctionKind("KExtensionFunction", true, "ExtensionFunction")
FUNCTION : FunctionKind("Function", "A function", false, null)
EXTENSION_FUNCTION : FunctionKind("ExtensionFunction", "An extension function", true, null)
K_FUNCTION : FunctionKind("KFunction", null, false, "Function")
K_MEMBER_FUNCTION : FunctionKind("KMemberFunction", null, true, "ExtensionFunction")
K_EXTENSION_FUNCTION : FunctionKind("KExtensionFunction", null, true, "ExtensionFunction")
fun getFileName() = (if (isReflection()) "reflect/" else "") + classNamePrefix + "s.kt"
fun getClassName(i: Int) = classNamePrefix + i
@@ -62,6 +63,7 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
override fun generateBody() {
for (i in 0..MAX_PARAM_COUNT) {
generateDocumentation(kind.docPrefix, i)
out.print("public trait " + kind.getClassName(i))
generateTypeParameters(i, true)
generateSuperClass(i)
@@ -69,6 +71,12 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
}
}
fun generateDocumentation(docPrefix: String?, i: Int) {
if (docPrefix == null) return
val suffix = if (i == 1) "" else "s"
out.println("/** $docPrefix that takes $i argument${suffix}. */")
}
fun generateSuperClass(i: Int) {
val superClass = kind.getSuperClassName(i)
if (superClass != null) {
@@ -89,6 +97,12 @@ class GenerateFunctions(out: PrintWriter, val kind: FunctionKind) : BuiltInsSour
}
fun generateInvokeSignature(i: Int) {
if (i == 0) {
out.println(" /** Invokes the function. */")
} else {
val suffix = if (i == 1) "" else "s"
out.println(" /** Invokes the function with the specified argument${suffix}. */")
}
out.print(" public fun ${if (kind.hasReceiverParameter) "T." else ""}invoke(")
for (j in 1..i) {
out.print("p$j: P$j")
generators/src/org/jetbrains/kotlin/generators/builtins/iterators.kt
+1 -1
View File
@@ -24,7 +24,7 @@ class GenerateIterators(out: PrintWriter) : BuiltInsSourceGenerator(out) {
override fun generateBody() {
for (kind in PrimitiveType.values()) {
val s = kind.capitalized
out.println("/** An iterator over a sequence of values of type $s. */")
out.println("/** An iterator over a sequence of values of type `$s`. */")
out.println("public abstract class ${s}Iterator : Iterator<$s> {" )
out.println(" override final fun next() = next$s()")
out.println()
generators/src/org/jetbrains/kotlin/generators/builtins/primitives.kt
+49 -12
View File
@@ -21,10 +21,26 @@ import org.jetbrains.kotlin.generators.builtins.generateBuiltIns.BuiltInsSourceG
import java.io.PrintWriter
class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
private val binaryOperators: List<String> = listOf("plus", "minus", "times", "div", "mod")
private val unaryOperators: List<String> = listOf("inc", "dec", "plus", "minus")
private val shiftOperators: List<String> = listOf("shl", "shr", "ushr")
private val bitwiseOperators: List<String> = listOf("and", "or", "xor")
private val binaryOperators: Map<String, String> = mapOf(
"plus" to "Adds the other value to this value.",
"minus" to "Subtracts the other value from this value.",
"times" to "Multiplies this value by the other value.",
"div" to "Divides this value by the other value.",
"mod" to "Calculates the remainder of dividing this value by the other value."
)
private val unaryOperators: Map<String, String> = mapOf(
"inc" to "Increments this value.",
"dec" to "Decrements this value.",
"plus" to "Returns this value.",
"minus" to "Returns the negative of this value.")
private val shiftOperators: Map<String, String> = mapOf(
"shl" to "Shifts this value left by [bits].",
"shr" to "Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit.",
"ushr" to "Shifts this value right by [bits], filling the leftmost bits with zeros.")
private val bitwiseOperators: Map<String, String> = mapOf(
"and" to "Performs a bitwise AND operation between the two values.",
"or" to "Performs a bitwise OR operation between the two values.",
"xor" to "Performs a bitwise XOR operation between the two values.")
private val typeDescriptions: Map<PrimitiveType, String> = hashMapOf(
PrimitiveType.DOUBLE to "double-precision 64-bit IEEE 754 floating point number",
PrimitiveType.FLOAT to "single-precision 32-bit IEEE 754 floating point number",
@@ -61,7 +77,7 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
generateBitwiseOperators(className)
}
generateConversions()
generateConversions(kind)
out.println("}\n")
}
@@ -76,6 +92,17 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
private fun generateCompareTo(thisKind: PrimitiveType) {
for (otherKind in PrimitiveType.exceptBoolean) {
out.println("/**")
if (thisKind == PrimitiveType.CHAR && otherKind != PrimitiveType.CHAR) {
out.println(" * Compares the character code of this character with the specified value for order.")
} else if (thisKind != PrimitiveType.CHAR && otherKind == PrimitiveType.CHAR) {
out.println(" * Compares this value with the character code of the specified character for order.")
} else {
out.println(" * Compares this value with the specified value for order.")
}
out.println(" * Returns zero if this value is equal to the specified other value, a negative number if its less than other, ")
out.println(" * or a positive number if its greater than other.")
out.println(" */")
out.print(" public ")
if (otherKind == thisKind) out.print("override ")
out.println("fun compareTo(other: ${otherKind.capitalized}): Int")
@@ -84,17 +111,18 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
}
private fun generateBinaryOperators(thisKind: PrimitiveType) {
for (name in binaryOperators) {
generateOperator(name, thisKind)
for ((name, doc) in binaryOperators) {
generateOperator(name, doc, thisKind)
}
}
private fun generateOperator(name: String, thisKind: PrimitiveType) {
private fun generateOperator(name: String, doc: String, thisKind: PrimitiveType) {
for (otherKind in PrimitiveType.exceptBoolean) {
if (thisKind == PrimitiveType.CHAR && otherKind == PrimitiveType.CHAR && name != "minus") {
continue
}
val returnType = getOperatorReturnType(thisKind, otherKind)
out.println(" /** $doc */")
out.println(" public fun $name(other: ${otherKind.capitalized}): $returnType")
}
out.println()
@@ -102,10 +130,12 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
private fun generateRangeTo(thisKind: PrimitiveType) {
if (thisKind == PrimitiveType.CHAR) {
out.println(" /** Creates a range from this value to the specified [other] value. */")
out.println(" public fun rangeTo(other: Char): CharRange")
} else {
for (otherKind in PrimitiveType.exceptBoolean) {
val returnType = if (otherKind.ordinal() > thisKind.ordinal()) otherKind else thisKind
out.println(" /** Creates a range from this value to the specified [other] value. */")
out.println(" public fun rangeTo(other: ${otherKind.capitalized}): ${returnType.capitalized}Range")
}
}
@@ -114,28 +144,35 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
}
private fun generateUnaryOperators(kind: PrimitiveType) {
for (name in unaryOperators) {
for ((name, doc) in unaryOperators) {
val returnType = if (kind in listOf(PrimitiveType.SHORT, PrimitiveType.BYTE, PrimitiveType.CHAR) &&
name in listOf("plus", "minus")) "Int" else kind.capitalized
out.println(" /** $doc */")
out.println(" public fun $name(): $returnType")
}
out.println()
}
private fun generateBitwiseOperators(className: String) {
for (name in shiftOperators) {
for ((name, doc) in shiftOperators) {
out.println(" /** $doc */")
out.println(" public fun $name(bits: Int): $className")
}
for (name in bitwiseOperators) {
for ((name, doc) in bitwiseOperators) {
out.println(" /** $doc */")
out.println(" public fun $name(other: $className): $className")
}
out.println(" /** Inverts the bits in this value/ */")
out.println(" public fun inv(): $className")
out.println()
}
private fun generateConversions() {
private fun generateConversions(kind: PrimitiveType) {
for (otherKind in PrimitiveType.exceptBoolean) {
val name = otherKind.capitalized
if (kind == PrimitiveType.CHAR) { // Char is not a Number and does not inherit Number's javadocs
out.println(" /** Returns the value of this character as a `$name`. */")
}
out.println(" public override fun to$name(): $name")
}
}
generators/src/org/jetbrains/kotlin/generators/builtins/progressionIterators.kt
+8 -2
View File
@@ -31,7 +31,10 @@ fun integerProgressionIterator(kind: ProgressionKind): String {
else -> "" to ""
}
return """/** An iterator over a progression of values of type $t. */
return """/**
* An iterator over a progression of values of type `$t`.
* @property increment the number by which the value is incremented on each step.
*/
class ${t}ProgressionIterator(start: $t, end: $t, val increment: $incrementType) : ${t}Iterator() {
private var next = start$toInt
private val finalElement: $t = getProgressionFinalElement(start$toInt, end$toInt, increment)$toType
@@ -55,7 +58,10 @@ class ${t}ProgressionIterator(start: $t, end: $t, val increment: $incrementType)
fun floatingPointProgressionIterator(kind: ProgressionKind): String {
val t = kind.capitalized
return """/** An iterator over a progression of values of type $t. */
return """/**
* An iterator over a progression of values of type `$t`.
* @property increment the number by which the value is incremented on each step.
*/
class ${t}ProgressionIterator(start: $t, val end: $t, val increment: $t) : ${t}Iterator() {
private var next = start
generators/src/org/jetbrains/kotlin/generators/builtins/progressions.kt
+1 -1
View File
@@ -66,7 +66,7 @@ class GenerateProgressions(out: PrintWriter) : BuiltInsSourceGenerator(out) {
out.println(
"""/**
* A progression of values of type $t.
* A progression of values of type `$t`.
*/
public class $progression(
override val start: $t,
generators/src/org/jetbrains/kotlin/generators/builtins/ranges.kt
+1 -1
View File
@@ -64,7 +64,7 @@ class GenerateRanges(out: PrintWriter) : BuiltInsSourceGenerator(out) {
out.println(
"""/**
* A range of values of type $t.
* A range of values of type `$t`.
*/
public class $range(override val start: $t, override val end: $t) : Range<$t>, Progression<$t> {
override val increment: $incrementType