From e34b3c529890d167bd91e3d2c0f1757e59f37b49 Mon Sep 17 00:00:00 2001
From: Alexander Udalov <Alexander.Udalov@jetbrains.com>
Date: Mon, 16 Mar 2015 20:28:57 +0300
Subject: [PATCH] Document interfaces in package kotlin.reflect

---
 core/builtins/src/kotlin/reflect/KCallable.kt |  8 ++++++
 core/builtins/src/kotlin/reflect/KClass.kt    | 18 +++++++++++++
 .../src/kotlin/reflect/KExtensionProperty.kt  | 22 ++++++++++++++++
 .../reflect/KMemberExtensionProperty.kt       | 26 +++++++++++++++++++
 .../src/kotlin/reflect/KMemberProperty.kt     | 21 +++++++++++++++
 core/builtins/src/kotlin/reflect/KPackage.kt  |  3 +++
 core/builtins/src/kotlin/reflect/KProperty.kt | 11 ++++++++
 .../reflect/KTopLevelExtensionProperty.kt     |  6 +++++
 .../src/kotlin/reflect/KTopLevelProperty.kt   |  6 +++++
 .../src/kotlin/reflect/KTopLevelVariable.kt   |  6 +++++
 core/builtins/src/kotlin/reflect/KVariable.kt | 16 ++++++++++++
 11 files changed, 143 insertions(+)

diff --git a/core/builtins/src/kotlin/reflect/KCallable.kt b/core/builtins/src/kotlin/reflect/KCallable.kt
index c9597bfa452..0f59c90242c 100644
--- a/core/builtins/src/kotlin/reflect/KCallable.kt
+++ b/core/builtins/src/kotlin/reflect/KCallable.kt
@@ -16,6 +16,14 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a callable entity, such as a function or a property.
+ *
+ * @param R return type of the callable.
+ */
 public trait KCallable<out R> {
+    /**
+     * The name of this callable as it was declared in the source code.
+     */
     public val name: String
 }
diff --git a/core/builtins/src/kotlin/reflect/KClass.kt b/core/builtins/src/kotlin/reflect/KClass.kt
index 9ced2887c28..552b7e68d8f 100644
--- a/core/builtins/src/kotlin/reflect/KClass.kt
+++ b/core/builtins/src/kotlin/reflect/KClass.kt
@@ -16,10 +16,28 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a class and provides introspection capabilities.
+ * Instances of this class are obtainable by the `::class` syntax.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/reflection.html#class-references)
+ * for more information.
+ *
+ * @param T the type of the class.
+ */
 public trait KClass<T> {
+    /**
+     * The simple name of the class as it was declared in the source code,
+     * or `null` if the class has no name (e.g. anonymous object literals).
+     */
     public val simpleName: String?
 
+    /**
+     * Returns non-extension properties declared in this class and all of its superclasses.
+     */
     public val properties: Collection<KMemberProperty<T, *>>
 
+    /**
+     * Returns extension properties declared in this class and all of its superclasses.
+     */
     public val extensionProperties: Collection<KMemberExtensionProperty<T, *, *>>
 }
diff --git a/core/builtins/src/kotlin/reflect/KExtensionProperty.kt b/core/builtins/src/kotlin/reflect/KExtensionProperty.kt
index e0ad3f86d93..4cefea1afa3 100644
--- a/core/builtins/src/kotlin/reflect/KExtensionProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KExtensionProperty.kt
@@ -16,10 +16,32 @@
 
 package kotlin.reflect
 
+/**
+ * Represents an extension property.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/extensions.html#extension-properties)
+ * for more information.
+ *
+ * @param E the type of the extension receiver.
+ * @param R the type of the property.
+ */
 public trait KExtensionProperty<E, out R> : KProperty<R> {
+    /**
+     * Returns the current value of the property.
+     *
+     * @param receiver the instance of the extension receiver.
+     */
     public fun get(receiver: E): R
 }
 
+/**
+ * Represents an extension property declared as a `var`.
+ */
 public trait KMutableExtensionProperty<E, R> : KExtensionProperty<E, R>, KMutableProperty<R> {
+    /**
+     * Modifies the value of the property.
+     *
+     * @param receiver the instance of the extension receiver.
+     * @param value the new value to be assigned to this property.
+     */
     public fun set(receiver: E, value: R)
 }
diff --git a/core/builtins/src/kotlin/reflect/KMemberExtensionProperty.kt b/core/builtins/src/kotlin/reflect/KMemberExtensionProperty.kt
index de55777311f..1841d37a7d5 100644
--- a/core/builtins/src/kotlin/reflect/KMemberExtensionProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KMemberExtensionProperty.kt
@@ -16,10 +16,36 @@
 
 package kotlin.reflect
 
+/**
+ * Represents an extension property declared in a class.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/extensions.html#extension-properties)
+ * for more information.
+ *
+ * @param T the type of the instance which should be used to obtain the value of the property.
+ *          Must be derived either from a class declaring this property, or any subclass of that class.
+ * @param E the type of the extension receiver.
+ * @param R the type of the property.
+ */
 public trait KMemberExtensionProperty<T : Any, E, out R> : KProperty<R> {
+    /**
+     * Returns the current value of the property.
+     *
+     * @param instance the instance to obtain the value of the property from.
+     * @param extensionReceiver the instance of the extension receiver.
+     */
     public fun get(instance: T, extensionReceiver: E): R
 }
 
+/**
+ * Represents a `var` extension property declared in a class.
+ */
 public trait KMutableMemberExtensionProperty<T : Any, E, R> : KMemberExtensionProperty<T, E, R>, KMutableProperty<R> {
+    /**
+     * Modifies the value of the property.
+     *
+     * @param instance the instance to obtain the value of the property from.
+     * @param extensionReceiver the instance of the extension receiver.
+     * @param value the new value to be assigned to this property.
+     */
     public fun set(instance: T, extensionReceiver: E, value: R)
 }
diff --git a/core/builtins/src/kotlin/reflect/KMemberProperty.kt b/core/builtins/src/kotlin/reflect/KMemberProperty.kt
index 4c5c8e7bc01..c0a517ea10b 100644
--- a/core/builtins/src/kotlin/reflect/KMemberProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KMemberProperty.kt
@@ -16,10 +16,31 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a property declared in a class.
+ *
+ * @param T the type of the instance which should be used to obtain the value of the property.
+ *          Must be derived either from a class declaring this property, or any subclass of that class.
+ * @param R the type of the property.
+ */
 public trait KMemberProperty<T : Any, out R> : KProperty<R> {
+    /**
+     * Returns the current value of the property.
+     *
+     * @param instance the instance to obtain the value of the property from.
+     */
     public fun get(instance: T): R
 }
 
+/**
+ * Represents a `var` property declared in a class.
+ */
 public trait KMutableMemberProperty<T : Any, R> : KMemberProperty<T, R>, KMutableProperty<R> {
+    /**
+     * Modifies the value of the property.
+     *
+     * @param instance the instance to obtain the value of the property from.
+     * @param value the new value to be assigned to this property.
+     */
     public fun set(instance: T, value: R)
 }
diff --git a/core/builtins/src/kotlin/reflect/KPackage.kt b/core/builtins/src/kotlin/reflect/KPackage.kt
index b626387ed40..b0161bded0d 100644
--- a/core/builtins/src/kotlin/reflect/KPackage.kt
+++ b/core/builtins/src/kotlin/reflect/KPackage.kt
@@ -16,4 +16,7 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a package and provides introspection capabilities.
+ */
 public trait KPackage
diff --git a/core/builtins/src/kotlin/reflect/KProperty.kt b/core/builtins/src/kotlin/reflect/KProperty.kt
index 0364cc8ed5c..311409a0a10 100644
--- a/core/builtins/src/kotlin/reflect/KProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KProperty.kt
@@ -16,6 +16,17 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a property, such as a named `val` or `var` declaration.
+ * Instances of this class are obtainable by the `::` operator.
+ * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/reflection.html)
+ * for more information.
+ *
+ * @param R the type of the property.
+ */
 public trait KProperty<out R> : KCallable<R>
 
+/**
+ * Represents a property declared as a `var`.
+ */
 public trait KMutableProperty<R> : KProperty<R>
diff --git a/core/builtins/src/kotlin/reflect/KTopLevelExtensionProperty.kt b/core/builtins/src/kotlin/reflect/KTopLevelExtensionProperty.kt
index 9e8efa9c702..229c915942b 100644
--- a/core/builtins/src/kotlin/reflect/KTopLevelExtensionProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KTopLevelExtensionProperty.kt
@@ -16,6 +16,12 @@
 
 package kotlin.reflect
 
+/**
+ * Represents an extension property declared in a package.
+ */
 public trait KTopLevelExtensionProperty<E, out R> : KExtensionProperty<E, R>, KTopLevelProperty<R>
 
+/**
+ * Represents a package extension property declared as a `var`.
+ */
 public trait KMutableTopLevelExtensionProperty<E, R> : KTopLevelExtensionProperty<E, R>, KMutableExtensionProperty<E, R>, KMutableTopLevelProperty<R>
diff --git a/core/builtins/src/kotlin/reflect/KTopLevelProperty.kt b/core/builtins/src/kotlin/reflect/KTopLevelProperty.kt
index b9b594b0c38..49f4ad5281e 100644
--- a/core/builtins/src/kotlin/reflect/KTopLevelProperty.kt
+++ b/core/builtins/src/kotlin/reflect/KTopLevelProperty.kt
@@ -16,6 +16,12 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a property declared in a package.
+ */
 public trait KTopLevelProperty<out R> : KProperty<R>
 
+/**
+ * Represents a package property declared as a `var`.
+ */
 public trait KMutableTopLevelProperty<R> : KTopLevelProperty<R>, KMutableProperty<R>
diff --git a/core/builtins/src/kotlin/reflect/KTopLevelVariable.kt b/core/builtins/src/kotlin/reflect/KTopLevelVariable.kt
index 660cc02e3a5..9df6e519008 100644
--- a/core/builtins/src/kotlin/reflect/KTopLevelVariable.kt
+++ b/core/builtins/src/kotlin/reflect/KTopLevelVariable.kt
@@ -16,6 +16,12 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a variable declared in a package.
+ */
 public trait KTopLevelVariable<out R> : KVariable<R>, KTopLevelProperty<R>
 
+/**
+ * Represents a package variable declared as a `var`.
+ */
 public trait KMutableTopLevelVariable<R> : KTopLevelVariable<R>, KMutableVariable<R>, KMutableTopLevelProperty<R>
diff --git a/core/builtins/src/kotlin/reflect/KVariable.kt b/core/builtins/src/kotlin/reflect/KVariable.kt
index 410dbbffe7d..ff1fec7a4b2 100644
--- a/core/builtins/src/kotlin/reflect/KVariable.kt
+++ b/core/builtins/src/kotlin/reflect/KVariable.kt
@@ -16,10 +16,26 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a property without any kind of receiver.
+ * Such property is either originally declared in a receiverless context such as a package,
+ * or has the receiver bound to it.
+ */
 public trait KVariable<out R> : KProperty<R> {
+    /**
+     * Returns the current value of the variable.
+     */
     public fun get(): R
 }
 
+/**
+ * Represents a variable declared as a `var`.
+ */
 public trait KMutableVariable<R> : KVariable<R>, KMutableProperty<R> {
+    /**
+     * Modifies the value of the variable.
+     *
+     * @param value the new value to be assigned to this variable.
+     */
     public fun set(value: R)
 }