Assorted stdlib KDocs

js/js.libraries/src/core/core.kt

@@ -5,8 +5,14 @@ public external val noImpl: Nothing
 
 public external val definedExternally: Nothing
 
+/**
+ * Exposes the JavaScript [eval function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) to Kotlin.
+ */
 public external fun eval(expr: String): dynamic
 
+/**
+ * Exposes the JavaScript [undefined property](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) to Kotlin.
+ */
 public external val undefined: Nothing?
 
 @Deprecated("Use toInt() instead.", ReplaceWith("s.toInt()"), level = DeprecationLevel.ERROR)

js/js.libraries/src/core/date.kt

@@ -1,5 +1,8 @@
 package kotlin.js
 
+/**
+ * Exposes the [Date API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) to Kotlin.
+ */
 public external class Date() {
     public fun getTime(): Double
 }

js/js.libraries/src/core/debug.kt

@@ -1,6 +1,8 @@
 package kotlin.js
 
-// https://developer.mozilla.org/en/DOM/console
+/**
+ * Exposes the [console API](https://developer.mozilla.org/en/DOM/console) to Kotlin.
+ */
 external public interface Console {
     public fun dir(o: Any): Unit
     public fun error(vararg o: Any?): Unit
@@ -9,4 +11,7 @@ external public interface Console {
     public fun warn(vararg o: Any?): Unit
 }
 
+/**
+ * Exposes the [console API](https://developer.mozilla.org/en/DOM/console) to Kotlin.
+ */
 public external val console: Console

js/js.libraries/src/core/dynamic.kt

@@ -16,6 +16,9 @@
 
 package kotlin.js
 
+/**
+ * Reinterprets this value as a value of the [dynamic type](/docs/reference/dynamic-type.html).
+ */
 @kotlin.internal.InlineOnly
 public inline fun Any?.asDynamic(): dynamic = this
 

js/js.libraries/src/core/json.kt

@@ -1,10 +1,52 @@
 package kotlin.js
 
+/**
+ * An interface for indexing access to a collection of key-value pairs, where type of key is [String] and type of value is [Any?].
+ */
 public external interface Json {
+    /**
+     * Calls to the function will be translated to indexing operation (square brackets) on the receiver with [propertyName] as the argument.
+     *
+     * E.g. for next code:
+     * ```kotlin
+     * fun test(j: Json, p: String) = j["prop"] + j.get(p)
+     * ```
+     *
+     * will be generated:
+     * ```js
+     * function test(j, p) {
+     *     return j["prop"] + j[p];
+     * }
+     * ```
+     */
     operator fun get(propertyName: String): Any?
+
+    /**
+     * Calls of the function will be translated to an assignment of [value] to the receiver indexed (with square brackets/index operation) with [propertyName].
+     *
+     * E.g. for the following code:
+     * ```kotlin
+     * fun test(j: Json, p: String, newValue: Any) {
+     *     j["prop"] = 1
+     *     j.set(p, newValue)
+     * }
+     * ```
+     *
+     * will be generated:
+     * ```js
+     * function test(j, p, newValue) {
+     *     j["prop"] = 1;
+     *     j[p] = newValue;
+     * }
+     * }
+     * ```
+     */
     operator fun set(propertyName: String, value: Any?): Unit
 }
 
+/**
+ * Returns a simple JavaScript object (as [Json]) using provided key-value pairs as names and values of its properties.
+ */
 public fun json(vararg pairs: Pair<String, Any?>): Json {
     val res: dynamic = js("({})")
     for ((name, value) in pairs) {
@@ -13,6 +55,10 @@ public fun json(vararg pairs: Pair<String, Any?>): Json {
     return res
 }
 
+/**
+ * Adds key-value pairs from [other] to [this].
+ * Returns the original receiver.
+ */
 public fun Json.add(other: Json): Json {
     val keys: Array<String> = js("Object").keys(other)
     for (key in keys) {
@@ -23,6 +69,9 @@ public fun Json.add(other: Json): Json {
     return this
 }
 
+/**
+ * Exposes the JavaScript [JSON object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) to Kotlin.
+ */
 public external object JSON {
     public fun stringify(o: Any?): String
     public fun stringify(o: Any?, replacer: (key: String, value: Any?) -> Any?): String

js/js.libraries/src/core/math.kt

@@ -1,6 +1,9 @@
 package kotlin.js
 
 //TODO: declare using number
+/**
+ * Exposes the JavaScript [Math object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Math) to Kotlin.
+ */
 public external object Math {
     public val PI: Double
     public fun random(): Double
@@ -27,5 +30,12 @@ public external object Math {
     public fun ceil(value: Number): Int
 }
 
+/**
+ * Returns the smaller of two values.
+ */
 public fun Math.min(a: Long, b: Long): Long = if (a <= b) a else b
-public fun Math.max(a: Long, b: Long): Long = if (a >= b) a else b
+
+/**
+ * Returns the greater of two values.
+ */
+public fun Math.max(a: Long, b: Long): Long = if (a >= b) a else b

js/js.libraries/src/core/promise.kt

@@ -16,6 +16,9 @@
 
 package kotlin.js
 
+/**
+ * Exposes the JavaScript [Promise object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) to Kotlin.
+ */
 public open external class Promise<out T>(executor: (resolve: (T) -> Unit, reject: (Throwable) -> Unit) -> Unit) {
     companion object {
         public fun <S> all(promise: Array<out Promise<S>>): Promise<Array<in S>>

js/js.libraries/src/core/regexp.kt

@@ -16,7 +16,9 @@
 
 package kotlin.js
 
-
+/**
+ * Exposes the JavaScript [RegExp object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/RegExp) to Kotlin.
+ */
 public external class RegExp(pattern: String, flags: String? = definedExternally) {
 
     public fun test(str: String): Boolean
@@ -35,17 +37,31 @@ public external class RegExp(pattern: String, flags: String? = definedExternally
     public val multiline: Boolean
 }
 
+/**
+ * Resets the regular expression so that subsequent [RegExp.test] and [RegExp.exec] calls will match starting with the beginning of the input string.
+ */
 public fun RegExp.reset() {
     lastIndex = 0
 }
 
 // TODO: Inherit from array or introduce asArray() extension
+/**
+ * Represents the return value of [RegExp.exec].
+ */
 public external interface RegExpMatch {
     public val index: Int
     public val input: String
     public val length: Int
 }
 
+/**
+ * Returns the entire text matched by [RegExp.exec] if the [index] parameter is 0, or the text matched by the capturing parenthesis
+ * at the given index.
+ */
 public inline operator fun RegExpMatch.get(index: Int): String? = asDynamic()[index]
 
-public inline fun RegExpMatch.asArray(): Array<out String?> = unsafeCast<Array<out String?>>()
+/**
+ * Converts the result of [RegExp.exec] to an array where the first element contains the entire matched text and each subsequent
+ * element is the text matched by each capturing parenthesis.
+ */
+public inline fun RegExpMatch.asArray(): Array<out String?> = unsafeCast<Array<out String?>>()

js/js.libraries/src/reflect/JsClass.kt

@@ -20,7 +20,13 @@ import getKClass
 import kotlin.reflect.KClass
 import kotlin.reflect.js.internal.KClassImpl
 
+/**
+ * Represents the constructor of a class. Instances of `JsClass` can be passed to JavaScript APIs that expect a constructor reference.
+ */
 external interface JsClass<T : Any> {
+    /**
+     * Returns the unqualified name of the class represented by this instance.
+     */
     val name: String
 }
 
@@ -31,8 +37,14 @@ external fun <T : Any> jsClass(): JsClass<T>
 val <T : Any> T.jsClass: JsClass<T>
     get() = js("Object").getPrototypeOf(this).constructor
 
+/**
+ * Obtains a constructor reference for the given `KClass`.
+ */
 val <T : Any> KClass<T>.js: JsClass<T>
     get() = (this as KClassImpl<T>).jClass
 
+/**
+ * Obtains a `KClass` instance for the given constructor reference.
+ */
 val <T : Any> JsClass<T>.kotlin: KClass<T>
     get() = getKClass(this)