Baku - Docs improvements
Grouped packages in overview in response to afergan@'s API usability
feedback.
Added usage examples for Coordinators in response to youngseokyoon@'s CR
feedback.
Change-Id: I3ecf6a9064c5544427063e0bbec0f95c1dfc49cd
diff --git a/baku-toolkit/lib/build.gradle b/baku-toolkit/lib/build.gradle
index 24f751f..ee8337b 100644
--- a/baku-toolkit/lib/build.gradle
+++ b/baku-toolkit/lib/build.gradle
@@ -156,6 +156,8 @@
doclet 'ch.raffael.doclets.pegdown.PegdownDoclet'
stylesheetFile = new File('lib/src/main/java/custom-styles.css')
bottom new File('lib/src/main/java/bottom.html').text
+ group 'API Surface', 'io.v.baku.toolkit'
+ group 'Component Packages', 'io.v.baku.toolkit.*:io.v.rx:io.v.rx.*'
}
if (JavaVersion.current().isJava8Compatible()) {
diff --git a/baku-toolkit/lib/src/main/java/custom-styles.css b/baku-toolkit/lib/src/main/java/custom-styles.css
index 7ea28ef..345a428 100644
--- a/baku-toolkit/lib/src/main/java/custom-styles.css
+++ b/baku-toolkit/lib/src/main/java/custom-styles.css
@@ -6,12 +6,17 @@
/* Links in code blocks don't display well by default. */
-a code {
+pre code code {
display: inline;
padding: 0;
- color: #4A6782;
+ color: inherit;
}
-a:hover code {
- color: #bb7a2a;
-}
+/*
+Although headings should be fine in class docs, the default stylesheet includes a
+ul.blockList li.blockList h2 style with padding-bottom: 20px for some reason.
+*/
+
+ul.blockList li.blockList .block h2 {
+ padding: initial;
+}
\ No newline at end of file
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/DebouncingCoordinator.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/DebouncingCoordinator.java
index 6e67a41..2382b7d 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/DebouncingCoordinator.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/DebouncingCoordinator.java
@@ -4,12 +4,14 @@
package io.v.baku.toolkit.bind;
+import android.view.View;
import android.widget.TextView;
import org.joda.time.Duration;
import java.util.concurrent.TimeUnit;
+import io.v.baku.toolkit.BakuActivityTrait;
import io.v.rx.syncbase.SingleWatchEvent;
import lombok.RequiredArgsConstructor;
import rx.Observable;
@@ -18,10 +20,12 @@
import rx.subjects.ReplaySubject;
/**
- * This coordinator defers the read binding until a specified timeout (default
- * {@value #DEFAULT_IO_DEBOUNCE_MILLIS} ms) after the latest write, then taking the latest read.
- * Write/watch latency can cause reflexive watch changes from Syncbase to arrive after subsequent
- * changes to the UI state have already been made, causing a stuttering revert.
+ * This coordinator defers the read binding until a specified delay after the latest write, then
+ * taking the latest read. Write/watch latency can cause reflexive watch changes from Syncbase to
+ * arrive after subsequent changes to the UI state have already been made, causing a stuttering
+ * revert.
+ *
+ * The default delay is 500 ms.
*
* A simple debounce on the uplink or downlink doesn't solve the problem because it effectively just
* adds a delay to the boundary condition. To prevent this, any update from the model must be
@@ -33,11 +37,23 @@
* This coordinator is included in the default coordinator chain for
* {@linkplain io.v.baku.toolkit.bind.SyncbaseBinding.Builder#bindTo(TextView) two-way
* <code>TextView</code> bindings}.
+ *
+ * ## Usage
+ *The following example shows how you would use this coordinator explicitly while creating a custom
+ * binding within a {@link io.v.baku.toolkit.BakuActivityTrait}:
+ *
+ * ```java
+ * {@link BakuActivityTrait#binder() binder()}.{@link
+ * io.v.baku.toolkit.bind.SyncbaseBinding.Builder#key(java.lang.String) key}("foo")
+ * .{@link io.v.baku.toolkit.bind.SyncbaseBinding.Builder#coordinators(CoordinatorChain[])
+ * coordinators}({@link DebouncingCoordinator#DebouncingCoordinator(TwoWayBinding)
+ * DebouncingCoordinator::new})
+ * .{@link io.v.baku.toolkit.bind.SyncbaseBinding.Builder#bindTo(View) bindTo}(myView);
+ * ```
*/
@RequiredArgsConstructor
public class DebouncingCoordinator<T> implements TwoWayBinding<T> {
- private static final long DEFAULT_IO_DEBOUNCE_MILLIS = 500;
- public static final Duration DEFAULT_IO_DEBOUNCE = Duration.millis(DEFAULT_IO_DEBOUNCE_MILLIS);
+ public static final Duration DEFAULT_IO_DEBOUNCE = Duration.millis(500);
private final TwoWayBinding<T> mChild;
private final Duration mIoDebounce;
@@ -49,6 +65,9 @@
//We expect these timeouts to be on the main thread; see putDebounceWindow
}
+ /**
+ * A reference to this constructor can be used as a {@link CoordinatorChain}.
+ */
public DebouncingCoordinator(final TwoWayBinding<T> child) {
this(child, DEFAULT_IO_DEBOUNCE);
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/SuppressWriteOnReadCoordinator.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/SuppressWriteOnReadCoordinator.java
index d93d352..c8bb28e 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/SuppressWriteOnReadCoordinator.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/SuppressWriteOnReadCoordinator.java
@@ -4,8 +4,10 @@
package io.v.baku.toolkit.bind;
+import android.view.View;
import android.widget.TextView;
+import io.v.baku.toolkit.BakuActivityTrait;
import io.v.rx.syncbase.SingleWatchEvent;
import lombok.RequiredArgsConstructor;
import rx.Observable;
@@ -22,6 +24,20 @@
* This coordinator is required (and injected if missing) in the coordinator chain for
* {@linkplain io.v.baku.toolkit.bind.SyncbaseBinding.Builder#bindTo(TextView) two-way
* <code>TextView</code> bindings}.
+ *
+ * ## Usage
+ *The following example shows how you would use this coordinator explicitly while creating a custom
+ * binding within a {@link io.v.baku.toolkit.BakuActivityTrait}:
+ *
+ * ```java
+ * {@link BakuActivityTrait#binder() binder()}.{@link
+ * io.v.baku.toolkit.bind.SyncbaseBinding.Builder#key(java.lang.String) key}("foo")
+ * .{@link io.v.baku.toolkit.bind.SyncbaseBinding.Builder#coordinators(CoordinatorChain[])
+ * coordinators}({@link
+ * SuppressWriteOnReadCoordinator#SuppressWriteOnReadCoordinator(TwoWayBinding)
+ * SuppressWriteOnReadCoordinator::new})
+ * .{@link io.v.baku.toolkit.bind.SyncbaseBinding.Builder#bindTo(View) bindTo}(myView);
+ * ```
*/
@RequiredArgsConstructor
public class SuppressWriteOnReadCoordinator<T> implements TwoWayBinding<T> {
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/package-info.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/package-info.java
index 1d86382..9f1ecf4 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/package-info.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/package-info.java
@@ -19,7 +19,7 @@
* super.onCreate(savedInstanceState);
* setContentView(R.layout.my_activity_layout);
*
- * {@link io.v.baku.toolkit.BakuActivityMixin#binder() binder}().{@link
+ * {@link io.v.baku.toolkit.BakuActivityTrait#binder() binder}().{@link
* io.v.baku.toolkit.bind.SyncbaseBinding.Builder#key(java.lang.String) key}("myDataRow")
* .{@link io.v.baku.toolkit.bind.SyncbaseBinding.Builder#bindTo(int)
* bindTo}(R.id.myTextView);
