Add some Javadoc comments

Author: yanex

anko/library/static/common/src/Async.kt

@@ -25,16 +25,27 @@ import java.util.concurrent.ExecutorService
 import java.util.concurrent.Executors
 import java.util.concurrent.Future
 
+/**
+ * Execute [f] on the application UI thread.
+ */
 fun Context.runOnUiThread(f: Context.() -> Unit) {
     if (ContextHelper.mainThread == Thread.currentThread()) f() else ContextHelper.handler.post { f() }
 }
 
+/**
+ * Execute [f] on the application UI thread.
+ */
 inline fun Fragment.runOnUiThread(crossinline f: () -> Unit) {
     activity?.runOnUiThread { f() }
 }
 
 class AnkoAsyncContext<T>(val weakRef: WeakReference<T>)
 
+/**
+ * Execute [f] on the application UI thread.
+ * If the [async] receiver still exists (was not collected by GC), 
+ *  [f] gets it as a parameter ([f] gets null if the receiver does not exist anymore).
+ */
 fun <T> AnkoAsyncContext<T>.onComplete(f: (T?) -> Unit) {
     val ref = weakRef.get()
     if (ContextHelper.mainThread == Thread.currentThread()) {
@@ -44,6 +55,11 @@ fun <T> AnkoAsyncContext<T>.onComplete(f: (T?) -> Unit) {
     }
 }
 
+/**
+ * Execute [f] on the application UI thread.
+ * [async] receiver will be passed to [f].
+ * If the receiver does not exist anymore (it was collected by GC), [f] will not be executed.
+ */
 fun <T> AnkoAsyncContext<T>.uiThread(f: (T) -> Unit): Boolean {
     val ref = weakRef.get() ?: return false
     if (ContextHelper.mainThread == Thread.currentThread()) {
@@ -54,6 +70,11 @@ fun <T> AnkoAsyncContext<T>.uiThread(f: (T) -> Unit): Boolean {
     return true
 }
 
+/**
+ * Execute [f] on the application UI thread if the underlying [Activity] still exists and is not finished.
+ * The receiver [Activity] will be passed to [f]. 
+ *  If it is not exist anymore or if it was finished, [f] will not be called.
+ */
 fun <T: Activity> AnkoAsyncContext<T>.activityUiThread(f: (T) -> Unit): Boolean {
     val activity = weakRef.get() ?: return false
     if (activity.isFinishing) return false
@@ -100,6 +121,13 @@ fun <T: Fragment> AnkoAsyncContext<T>.fragmentUiThreadWithContext(f: Context.(T)
     return true
 }
 
+/**
+ * Execute [task] asynchronously.
+ * 
+ * @param exceptionHandler optional exception handler. 
+ *  If defined, any exceptions thrown inside [task] will be passed to it. If not, exceptions will be ignored.
+ * @param task the code to execute asynchronously.
+ */
 fun <T> T.doAsync(
         exceptionHandler: ((Throwable) -> Unit)? = null,
         task: AnkoAsyncContext<T>.() -> Unit

anko/library/static/common/src/Arrays.kt renamed to anko/library/static/common/src/collections/Arrays.kt

@@ -21,20 +21,35 @@ import android.util.SparseBooleanArray
 import android.util.SparseIntArray
 import java.util.*
 
+/**
+ * Iterate the receiver [Array] using an index.
+ *
+ * @f an action to invoke on each array element.
+ */
 inline fun <T> Array<T>.forEachByIndex(f: (T) -> Unit) {
     val lastIndex = size - 1
     for (i in 0..lastIndex) {
         f(get(i))
     }
 }
 
+/**
+ * Iterate the receiver [Array] using an index.
+ *
+ * @f an action to invoke on each array element (index, element).
+ */
 inline fun <T> Array<T>.forEachWithIndex(f: (Int, T) -> Unit) {
     val lastIndex = size - 1
     for (i in 0..lastIndex) {
         f(i, get(i))
     }
 }
 
+/**
+ * Iterate the receiver [Array] backwards using an index.
+ *
+ * @f an action to invoke on each array element.
+ */
 inline fun <T> Array<T>.forEachReversedByIndex(f: (T) -> Unit) {
     var i = size - 1
     while (i >= 0) {
@@ -43,6 +58,11 @@ inline fun <T> Array<T>.forEachReversedByIndex(f: (T) -> Unit) {
     }
 }
 
+/**
+ * Iterate the receiver [Array] backwards using an index.
+ *
+ * @f an action to invoke on each array element (index, element).
+ */
 inline fun <T> Array<T>.forEachReversedWithIndex(f: (Int, T) -> Unit) {
     var i = size - 1
     while (i >= 0) {
@@ -51,10 +71,19 @@ inline fun <T> Array<T>.forEachReversedWithIndex(f: (Int, T) -> Unit) {
     }
 }
 
+/**
+ * Create a [Sequence] instance that wraps the original [SparseArray] returning its elements when being iterated.
+ */
 fun <T> SparseArray<T>.asSequence(): Sequence<T> = SparseArraySequence(this)
 
+/**
+ * Create a [Sequence] instance that wraps the original [SparseBooleanArray] returning its elements when being iterated.
+ */
 fun <T> SparseBooleanArray.asSequence(): Sequence<Boolean> = SparseBooleanArraySequence(this)
 
+/**
+ * Create a [Sequence] instance that wraps the original [SparseIntArray] returning its elements when being iterated.
+ */
 fun <T> SparseIntArray.asSequence(): Sequence<Int> = SparseIntArraySequence(this)
 
 private class SparseArraySequence<T>(private val a: SparseArray<T>) : Sequence<T> {

anko/library/static/common/src/Collections.kt renamed to anko/library/static/common/src/collections/Collections.kt

@@ -17,7 +17,7 @@
 package org.jetbrains.anko.collections
 
 /**
- * Iterate the [List] using an index.
+ * Iterate the receiver [List] using an index.
  *
  * @f an action to invoke on each list element.
  */
@@ -29,7 +29,7 @@ inline fun <T> List<T>.forEachByIndex(f: (T) -> Unit) {
 }
 
 /**
- * Iterate the [List] using an index.
+ * Iterate the receiver [List] using an index.
  *
  * @f an action to invoke on each list element (index, element).
  */
@@ -41,7 +41,7 @@ inline fun <T> List<T>.forEachWithIndex(f: (Int, T) -> Unit) {
 }
 
 /**
- * Iterate the [List] backwards using an index.
+ * Iterate the receiver [List] backwards using an index.
  *
  * @f an action to invoke on each list element.
  */
@@ -54,7 +54,7 @@ inline fun <T> List<T>.forEachReversedByIndex(f: (T) -> Unit) {
 }
 
 /**
- * Iterate the [List] backwards using an index.
+ * Iterate the receiver [List] backwards using an index.
  *
  * @f an action to invoke on each list element (index, element).
  */

anko/library/static/common/src/AlertDialogBuilder.kt renamed to anko/library/static/common/src/dialogs/AlertDialogBuilder.kt

@@ -22,93 +22,6 @@ import android.app.ProgressDialog
 import android.content.Context
 import android.widget.Toast
 
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text resource.
- */
-inline fun AnkoContext<*>.toast(message: Int) = ctx.toast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text resource.
- */
-inline fun Fragment.toast(message: Int): Unit = activity.toast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text resource.
- */
-fun Context.toast(message: Int) = Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text.
- */
-inline fun AnkoContext<*>.toast(message: CharSequence) = ctx.toast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text.
- */
-inline fun Fragment.toast(message: CharSequence): Unit = activity.toast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_SHORT] duration.
- *
- * @param message the message text.
- */
-fun Context.toast(message: CharSequence) = Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text resource.
- */
-inline fun AnkoContext<*>.longToast(message: Int) = ctx.longToast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text resource.
- */
-inline fun Fragment.longToast(message: Int): Unit = activity.longToast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text resource.
- */
-fun Context.longToast(message: Int) = Toast.makeText(this, message, Toast.LENGTH_LONG).show()
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text.
- */
-inline fun AnkoContext<*>.longToast(message: CharSequence) = ctx.longToast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text.
- */
-inline fun Fragment.longToast(message: CharSequence): Unit = activity.longToast(message)
-
-/**
- * Display the simple Toast message with the [Toast.LENGTH_LONG] duration.
- *
- * @param message the message text.
- */
-fun Context.longToast(message: CharSequence) = Toast.makeText(this, message, Toast.LENGTH_LONG).show()
-
-
-/* Alerts */
-
 inline fun AnkoContext<*>.alert(
         message: String,
         title: String? = null,
@@ -160,9 +73,6 @@ inline fun Fragment.alert(noinline init: AlertDialogBuilder.() -> Unit): AlertDi
 
 fun Context.alert(init: AlertDialogBuilder.() -> Unit) = AlertDialogBuilder(this).apply { init() }
 
-
-/* Progress dialogs */
-
 inline fun AnkoContext<*>.progressDialog(
         message: Int? = null,
         title: Int? = null,
@@ -251,31 +161,4 @@ private fun Context.progressDialog(
     if (title != null) setTitle(title)
     if (init != null) init()
     show()
-}
-
-
-/* Selectors */
-
-inline fun AnkoContext<*>.selector(
-        title: CharSequence? = null,
-        items: List<CharSequence>,
-        noinline onClick: (Int) -> Unit
-): Unit = ctx.selector(title, items, onClick)
-
-inline fun Fragment.selector(
-        title: CharSequence? = null,
-        items: List<CharSequence>,
-        noinline onClick: (Int) -> Unit
-): Unit = activity.selector(title, items, onClick)
-
-fun Context.selector(
-    title: CharSequence? = null,
-    items: List<CharSequence>,
-    onClick: (Int) -> Unit
-) {
-    with(AlertDialogBuilder(this)) {
-        if (title != null) title(title)
-        items(items, onClick)
-        show()
-    }
 }

anko/library/static/common/src/Dialogs.kt renamed to anko/library/static/common/src/dialogs/Dialogs.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2016 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@file:Suppress("NOTHING_TO_INLINE")
+package org.jetbrains.anko
+
+import android.app.Fragment
+import android.content.Context
+
+inline fun AnkoContext<*>.selector(
+        title: CharSequence? = null,
+        items: List<CharSequence>,
+        noinline onClick: (Int) -> Unit
+): Unit = ctx.selector(title, items, onClick)
+
+inline fun Fragment.selector(
+        title: CharSequence? = null,
+        items: List<CharSequence>,
+        noinline onClick: (Int) -> Unit
+): Unit = activity.selector(title, items, onClick)
+
+fun Context.selector(
+        title: CharSequence? = null,
+        items: List<CharSequence>,
+        onClick: (Int) -> Unit
+) {
+    with(AlertDialogBuilder(this)) {
+        if (title != null) title(title)
+        items(items, onClick)
+        show()
+    }
+}