Skip to content

Fixed broken kdoc links and some other warnings. #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 29, 2019
Merged

Fixed broken kdoc links and some other warnings. #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions kotlin/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}",
Expand All @@ -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
Expand All @@ -112,6 +114,11 @@ buildscript {
}
}

rootProject.ext.defaultDokkaConfig = {
outputFormat = 'gfm'
outputDirectory = "$buildDir/docs"
}

rootProject.ext.defaultAndroidConfig = {
compileSdkVersion versions.targetSdkVersion
buildToolsVersion versions.buildToolsVersion
Expand Down
4 changes: 2 additions & 2 deletions kotlin/viewregistry-android/src/main/java/com/squareup/viewregistry/ModalContainer.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down
3 changes: 3 additions & 0 deletions kotlin/viewregistry/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions kotlin/workflow-core/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 2 additions & 3 deletions kotlin/workflow-core/src/main/java/com/squareup/workflow/StatefulWorkflow.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion kotlin/workflow-core/src/main/java/com/squareup/workflow/Workflow.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
*
Expand Down
52 changes: 29 additions & 23 deletions kotlin/workflow-core/src/main/java/com/squareup/workflow/WorkflowContext.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
*
Expand All @@ -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].
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: no longer really an or situation, since we unified the methods.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are still related though, and I want to avoid confusion about people trying to call them directly.

* 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.
Expand All @@ -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
Expand Down Expand Up @@ -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(
Expand All @@ -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(
Expand Down
10 changes: 5 additions & 5 deletions kotlin/workflow-host/src/main/java/com/squareup/workflow/WorkflowHost.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions kotlin/workflow-rx2/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions kotlin/workflow-testing/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down