Merge pull request #232 from square/zachklipp/fix-kdoc

Fixed broken kdoc links and some other warnings.

Author: zach-klippenstein

kotlin/build.gradle

@@ -74,6 +74,7 @@ buildscript {
               'mockito': "com.nhaarman:mockito-kotlin-kt1.1:${versions.mockitoKotlin}"
           ]
       ],
+      'dokkaAndroid': "org.jetbrains.dokka:dokka-android-gradle-plugin:${versions.dokka}",
       'dokka': "org.jetbrains.dokka:dokka-gradle-plugin:${versions.dokka}",
       'mavenPublish': "com.vanniktech:gradle-maven-publish-plugin:${versions.mavenPublishPlugin}",
       'ktlint': "gradle.plugin.org.jlleitschuh.gradle:ktlint-gradle:${versions.ktlintPlugin}",
@@ -100,6 +101,7 @@ buildscript {
     classpath deps.android_gradle_plugin
     classpath deps.detekt
     classpath deps.dokka
+    classpath deps.dokkaAndroid
     classpath deps.kotlin.gradlePlugin
     classpath deps.ktlint
     classpath deps.mavenPublish
@@ -112,6 +114,11 @@ buildscript {
   }
 }
 
+rootProject.ext.defaultDokkaConfig = {
+    outputFormat = 'gfm'
+    outputDirectory = "$buildDir/docs"
+}
+
 rootProject.ext.defaultAndroidConfig = {
   compileSdkVersion versions.targetSdkVersion
   buildToolsVersion versions.buildToolsVersion

kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt

@@ -96,9 +96,9 @@ abstract class ModalContainer<M : Any>
         .subscribe {
           removeAllViews()
           val newView = it.viewForBase(screens, viewRegistry, this)
-          restoredBaseViewState?.let {
+          restoredBaseViewState?.let { restoredState ->
             restoredBaseViewState = null
-            newView.restoreHierarchyState(it)
+            newView.restoreHierarchyState(restoredState)
           }
           addView(newView)
         }

kotlin/viewregistry/build.gradle

@@ -16,12 +16,15 @@
 apply plugin: 'java-library'
 apply plugin: 'kotlin'
 apply plugin: 'com.vanniktech.maven.publish'
+apply plugin: 'org.jetbrains.dokka'
 
 sourceCompatibility = JavaVersion.VERSION_1_7
 targetCompatibility = JavaVersion.VERSION_1_7
 
 kotlin.experimental.coroutines 'enable'
 
+dokka rootProject.ext.defaultDokkaConfig
+
 dependencies {
   api deps.kotlin.stdLib.jdk6
   api deps.okio

kotlin/workflow-core/build.gradle

@@ -16,12 +16,15 @@
 apply plugin: 'java-library'
 apply plugin: 'kotlin'
 apply plugin: 'com.vanniktech.maven.publish'
+apply plugin: 'org.jetbrains.dokka'
 
 sourceCompatibility = JavaVersion.VERSION_1_7
 targetCompatibility = JavaVersion.VERSION_1_7
 
 kotlin.experimental.coroutines 'enable'
 
+dokka rootProject.ext.defaultDokkaConfig
+
 dependencies {
   compileOnly deps.annotations.intellij
 

kotlin/workflow-core/src/main/java/com/squareup/workflow/StatefulWorkflow.kt

@@ -18,8 +18,7 @@ package com.squareup.workflow
 /**
  * A composable, stateful object that can [handle events][WorkflowContext.onEvent],
  * [delegate to children][WorkflowContext.compose], [subscribe][onReceive] to arbitrary streams from
- * the outside world, and be [saved][snapshotState] to a serialized form to be
- * [restored][restoreState] later.
+ * the outside world, and be [saved][snapshotState] to a serialized form to be restored later.
  *
  * The basic purpose of a `Workflow` is to take some [input][InputT] and return a
  * [rendering][RenderingT]. To that end, a workflow may keep track of internal [state][StateT],
@@ -39,7 +38,7 @@ package com.squareup.workflow
  *
  * @param StateT Typically a data class that contains all of the internal state for this workflow.
  * The state is seeded via [input][InputT] in [initialState]. It can be [serialized][snapshotState]
- * and later used to [restore][restoreState] the workflow. **Implementations of the `Workflow`
+ * and later used to restore the workflow. **Implementations of the `Workflow`
  * interface should not generally contain their own state directly.** They may inject objects like
  * instances of their child workflows, or network clients, but should not contain directly mutable
  * state. This is the only type parameter that a parent workflow needn't care about for its children,

kotlin/workflow-core/src/main/java/com/squareup/workflow/Workflow.kt

@@ -43,7 +43,7 @@ package com.squareup.workflow
  * If your workflow needs to keep track of internal state, implement the [StatefulWorkflow]
  * interface. That interface has an additional type parameter, `StateT`, and allows you to specify
  * [how to create the initial state][StatefulWorkflow.initialState] and how to
- * [snapshot][StatefulWorkflow.snapshotState]/[restore][StatefulWorkflow.restoreState] your state.
+ * [snapshot][StatefulWorkflow.snapshotState]/restore your state.
  *
  * ### [Stateless Workflows][StatelessWorkflow]
  *

kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt

@@ -44,9 +44,9 @@ import kotlin.reflect.KType
 interface WorkflowContext<StateT : Any, in OutputT : Any> {
 
   /**
-   * Given a function that takes an [event][EventT] and can mutate the state or emit an output, returns
-   * a function that will perform that workflow update when called with an event.
-   * The returned function is valid until the next [compose][Workflow.compose] pass.
+   * Given a function that takes an [event][EventT] and can mutate the state or emit an output,
+   * returns a function that will perform that workflow update when called with an event.
+   * The returned function is valid until the next compose pass.
    *
    * For example, if you have a rendering type of `Screen`:
    *
@@ -73,16 +73,16 @@ interface WorkflowContext<StateT : Any, in OutputT : Any> {
   ): EventHandler<EventT>
 
   /**
-   * Ensures that the [channel][ReceiveChannel] returned from [channelProvider] is subscribed to, and
-   * will send anything emitted on the channel to [handler] as a [ChannelUpdate].
+   * Ensures that the [channel][ReceiveChannel] returned from [channelProvider] is subscribed to,
+   * and will send anything emitted on the channel to [handler] as a [ChannelUpdate].
    *
    * This method ensures that only one subscription is active at a time for the given [type]+[key].
-   * If this method is called in two or more consecutive [Workflow.compose] invocations with the same
-   * key, [channelProvider] will only be invoked for the first one, and the returned channel will be
-   * re-used for all subsequent invocations, until a [Workflow.compose] invocation does _not_ call this
-   * method with an equal key. At that time, the channel will be [cancelled][ReceiveChannel.cancel],
-   * with the assumption that cancelling the channel will release any resources allocated by the
-   * [channelProvider].
+   * If this method is called in two or more consecutive `compose` invocations with the
+   * same key, [channelProvider] will only be invoked for the first one, and the returned channel
+   * will be re-used for all subsequent invocations, until a `compose` invocation does
+   * _not_ call this method with an equal key. At that time, the channel will be
+   * [cancelled][ReceiveChannel.cancel], with the assumption that cancelling the channel will
+   * release any resources allocated by the [channelProvider].
    *
    * @param type The [KType] that represents both the type of data source (e.g. `ReceiveChannel` or
    * `Deferred`) and the element type [E].
@@ -101,18 +101,21 @@ interface WorkflowContext<StateT : Any, in OutputT : Any> {
 
   /**
    * Ensures [child] is running as a child of this workflow, and returns the result of its
-   * [compose][Workflow.compose] method.
+   * `compose` method.
    *
-   * **Never call [Workflow.compose] directly, always do it through this context method.**
+   * **Never call [StatefulWorkflow.compose] or [StatelessWorkflow.compose] directly, always do it
+   * through this context method.**
    *
    * 1. If the child _wasn't_ already running, it will be started either from
    *    [initialState][Workflow.initialState] or its snapshot.
-   * 2. If the child _was_ already running, The workflow's [onInputChanged][Workflow.onInputChanged]
-   *    method is invoked with the previous input and this one.
-   * 3. The child's [compose][Workflow.compose] method is invoked with `input` and the child's state.
+   * 2. If the child _was_ already running, The workflow's
+   *    [onInputChanged][StatefulWorkflow.onInputChanged] method is invoked with the previous input
+   *    and this one.
+   * 3. The child's `compose` method is invoked with `input` and the child's state.
    *
    * After this method returns, if something happens that trigger's one of `child`'s handlers, and
-   * that handler emits an output, the function passed as [handler] will be invoked with that output.
+   * that handler emits an output, the function passed as [handler] will be invoked with that
+   * output.
    *
    * @param key An optional string key that is used to distinguish between workflows of the same
    * type.
@@ -130,14 +133,15 @@ interface WorkflowContext<StateT : Any, in OutputT : Any> {
  * will send anything emitted on the channel to [handler] as a [ChannelUpdate].
  *
  * This method ensures that only one subscription is active at a time for the given key.
- * If this method is called in two or more consecutive [Workflow.compose] invocations with the same
+ * If this method is called in two or more consecutive `compose` invocations with the same
  * key+[channelProvider] type, the provider will only be invoked for the first one, and the returned
- * channel will be re-used for all subsequent invocations, until a [Workflow.compose] invocation does
- * _not_ call this method with an equal key+type. At that time, the channel will be
+ * channel will be re-used for all subsequent invocations, until a `compose` invocation
+ * does _not_ call this method with an equal key+type. At that time, the channel will be
  * [cancelled][ReceiveChannel.cancel], with the assumption that cancelling the channel will release
  * any resources allocated by the [channelProvider].
  *
- * @param key An optional string key that is used to distinguish between subscriptions of the same type.
+ * @param key An optional string key that is used to distinguish between subscriptions of the same
+ * type.
  * @param handler A function that returns the [WorkflowAction] to perform when the channel emits.
  *
  * @see WorkflowContext.onReceive
@@ -168,7 +172,8 @@ fun <StateT : Any, OutputT : Any, ChildOutputT : Any, ChildRenderingT : Any>
 // @formatter:on
 
 /**
- * Convenience alias of [WorkflowContext.compose] for workflows that don't take input or emit output.
+ * Convenience alias of [WorkflowContext.compose] for workflows that don't take input or emit
+ * output.
  */
 fun <InputT : Any, StateT : Any, OutputT : Any, ChildRenderingT : Any>
     WorkflowContext<StateT, OutputT>.compose(
@@ -182,7 +187,8 @@ fun <InputT : Any, StateT : Any, OutputT : Any, ChildRenderingT : Any>
 // @formatter:on
 
 /**
- * Convenience alias of [WorkflowContext.compose] for workflows that don't take input or emit output.
+ * Convenience alias of [WorkflowContext.compose] for workflows that don't take input or emit
+ * output.
  */
 fun <StateT : Any, OutputT : Any, ChildRenderingT : Any>
     WorkflowContext<StateT, OutputT>.compose(

kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt

@@ -37,8 +37,7 @@ import kotlin.coroutines.experimental.EmptyCoroutineContext
 interface WorkflowHost<out OutputT : Any, out RenderingT : Any> {
 
   /**
-   * Output from a [WorkflowHost]. Emitted from [WorkflowHost.updates] after every
-   * [compose][Workflow.compose] pass.
+   * Output from a [WorkflowHost]. Emitted from [WorkflowHost.updates] after every compose pass.
    */
   data class Update<out OutputT : Any, out RenderingT : Any>(
     val rendering: RenderingT,
@@ -61,11 +60,12 @@ interface WorkflowHost<out OutputT : Any, out RenderingT : Any> {
     /**
      * Creates a [WorkflowHost] to run [workflow].
      *
-     * The workflow's initial state is determined by passing [input] to [Workflow.initialState].
+     * The workflow's initial state is determined by passing [input] to
+     * [StatefulWorkflow.initialState].
      *
      * @param workflow The workflow to start.
-     * @param input Passed to [Workflow.initialState] to determine the root workflow's initial state.
-     * If [InputT] is `Unit`, you can just omit this argument.
+     * @param input Passed to [StatefulWorkflow.initialState] to determine the root workflow's
+     * initial state. If [InputT] is `Unit`, you can just omit this argument.
      * @param snapshot If not null, used to restore the workflow.
      * @param context The [CoroutineContext] used to run the workflow tree. Added to the [Factory]'s
      * context.

kotlin/workflow-rx2/build.gradle

@@ -16,12 +16,15 @@
 apply plugin: 'java-library'
 apply plugin: 'kotlin'
 apply plugin: 'com.vanniktech.maven.publish'
+apply plugin: 'org.jetbrains.dokka'
 
 sourceCompatibility = JavaVersion.VERSION_1_7
 targetCompatibility = JavaVersion.VERSION_1_7
 
 kotlin.experimental.coroutines 'enable'
 
+dokka rootProject.ext.defaultDokkaConfig
+
 dependencies {
   compileOnly deps.annotations.intellij
 

kotlin/workflow-testing/build.gradle

@@ -16,12 +16,15 @@
 apply plugin: 'java-library'
 apply plugin: 'kotlin'
 apply plugin: 'com.vanniktech.maven.publish'
+apply plugin: 'org.jetbrains.dokka'
 
 sourceCompatibility = JavaVersion.VERSION_1_7
 targetCompatibility = JavaVersion.VERSION_1_7
 
 kotlin.experimental.coroutines 'enable'
 
+dokka rootProject.ext.defaultDokkaConfig
+
 dependencies {
   compileOnly deps.annotations.intellij