diff --git a/kotlin/build.gradle b/kotlin/build.gradle index 8afd2078c..33680cfc2 100644 --- a/kotlin/build.gradle +++ b/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 diff --git a/kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt b/kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt index 2dfa9885b..9703db2fc 100644 --- a/kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt +++ b/kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt @@ -96,9 +96,9 @@ abstract class ModalContainer .subscribe { removeAllViews() val newView = it.viewForBase(screens, viewRegistry, this) - restoredBaseViewState?.let { + restoredBaseViewState?.let { restoredState -> restoredBaseViewState = null - newView.restoreHierarchyState(it) + newView.restoreHierarchyState(restoredState) } addView(newView) } diff --git a/kotlin/viewregistry/build.gradle b/kotlin/viewregistry/build.gradle index 19be55f82..ede5748e2 100644 --- a/kotlin/viewregistry/build.gradle +++ b/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 diff --git a/kotlin/workflow-core/build.gradle b/kotlin/workflow-core/build.gradle index 94afcdac9..b62172692 100644 --- a/kotlin/workflow-core/build.gradle +++ b/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 diff --git a/kotlin/workflow-core/src/main/java/com/squareup/workflow/StatefulWorkflow.kt b/kotlin/workflow-core/src/main/java/com/squareup/workflow/StatefulWorkflow.kt index 5b93a71ba..1444dd4f8 100644 --- a/kotlin/workflow-core/src/main/java/com/squareup/workflow/StatefulWorkflow.kt +++ b/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, diff --git a/kotlin/workflow-core/src/main/java/com/squareup/workflow/Workflow.kt b/kotlin/workflow-core/src/main/java/com/squareup/workflow/Workflow.kt index eb5dccba0..96d6305f0 100644 --- a/kotlin/workflow-core/src/main/java/com/squareup/workflow/Workflow.kt +++ b/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] * diff --git a/kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt b/kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt index 535b56bba..4ca77ec5c 100644 --- a/kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt +++ b/kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt @@ -44,9 +44,9 @@ import kotlin.reflect.KType interface WorkflowContext { /** - * 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 { ): EventHandler /** - * 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 { /** * 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 { * 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 // @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 WorkflowContext.compose( @@ -182,7 +187,8 @@ fun // @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 WorkflowContext.compose( diff --git a/kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt b/kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt index 2a5e60f57..5b2a4177b 100644 --- a/kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt +++ b/kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt @@ -37,8 +37,7 @@ import kotlin.coroutines.experimental.EmptyCoroutineContext interface WorkflowHost { /** - * 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( val rendering: RenderingT, @@ -61,11 +60,12 @@ interface WorkflowHost { /** * 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. diff --git a/kotlin/workflow-rx2/build.gradle b/kotlin/workflow-rx2/build.gradle index bca94c629..95a0fe9f8 100644 --- a/kotlin/workflow-rx2/build.gradle +++ b/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 diff --git a/kotlin/workflow-testing/build.gradle b/kotlin/workflow-testing/build.gradle index ba084731b..38c1b8f3e 100644 --- a/kotlin/workflow-testing/build.gradle +++ b/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