Document interfaces in package kotlin.reflect

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
 }

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, *, *>>
 }

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)
 }

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)
 }

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)
 }

core/builtins/src/kotlin/reflect/KPackage.kt

@@ -16,4 +16,7 @@
 
 package kotlin.reflect
 
+/**
+ * Represents a package and provides introspection capabilities.
+ */
 public trait KPackage

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>

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>

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>

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>

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)
 }