TBR: Reorganizing toolkit docs
Change-Id: Ia0b964164174e7f60fa021f831e3c05230c4ca4f
diff --git a/baku-toolkit/lib/build.gradle b/baku-toolkit/lib/build.gradle
index ee8337b..976369b 100644
--- a/baku-toolkit/lib/build.gradle
+++ b/baku-toolkit/lib/build.gradle
@@ -11,7 +11,7 @@
import org.gradle.language.base.internal.compile.Compiler
// You should change this after releasing a new version of the Baku Toolkit. See the
// list of published versions at https://repo1.maven.org/maven2/io/v/baku-toolkit.
-version = '0.8.0'
+version = '0.8.1'
group = 'io.v'
def siteUrl = 'https://github.com/vanadium/java'
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivity.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivity.java
index 0277502..99245be 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivity.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivity.java
@@ -15,13 +15,36 @@
* A default integration with {@link BakuActivityTrait} extending {@link android.app.Activity}. Most
* activities with distributed state should inherit from this.
*
- * @see io.v.baku.toolkit
+ * Example usage:
+ *
+ * ```java
+ * public class SampleBakuActivity extends BakuActivity {
+ * {@literal @}Override
+ * protected void onCreate(final Bundle savedInstanceState) {
+ * super.onCreate(savedInstanceState);
+ * setContentView(R.layout.my_activity_layout);
+ *
+ * // Example binding between "myDataRow" in Syncbase and myTextView in my_activity_layout.
+ * {@link #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);
+ * }
+ * }
+ * ```
+ *
+ * @see BakuAppCompatActivity
*/
@Slf4j
public abstract class BakuActivity extends VActivity implements BakuActivityTrait<Activity> {
@Delegate
private BakuActivityTrait<Activity> mBakuActivityTrait;
+ /**
+ * Instantiates the {@link BakuActivityTrait} implementation for this Activity. By default, this
+ * uses {@link BakuActivityMixin}.
+ */
protected BakuActivityTrait<Activity> createBakuActivityTrait() {
return new BakuActivityMixin<>(this);
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityMixin.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityMixin.java
index 6158d50..cfa1cfe 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityMixin.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityMixin.java
@@ -17,20 +17,48 @@
import lombok.experimental.Accessors;
import lombok.extern.slf4j.Slf4j;
import rx.subscriptions.CompositeSubscription;
+import rx.subscriptions.Subscriptions;
/**
- * Activity mix-in for activities with distributed UI state. By default, shared state is stored
- * in Syncbase under _app.package.name_/db/ui.
+ * Backing [mix-in](package-summary.html#mixins) for {@link BakuActivityTrait}. By default, shared
+ * state is stored in Syncbase under _app.package.name_/db/ui.
*
- * Default activity extensions incorporating this mix-in are available:
+ * Default `Activity` subclasses incorporating this mix-in are available:
*
- * * {@link BakuActivity} (extends {@link Activity})
- * * {@link BakuAppCompatActivity} (extends {@link android.support.v7.app.AppCompatActivity})
+ * * {@link BakuActivity} (`extends {@link Activity}`)
+ * * {@link BakuAppCompatActivity} (`extends {@link android.support.v7.app.AppCompatActivity}`)
*
* Since Java doesn't actually support multiple inheritance, clients requiring custom inheritance
* hierarchies will need to wire in manually, like any of the examples above. Alternatively, this
- * class may be used via pure composition, as detailed at
- * {@link BakuActivityMixin#BakuActivityMixin(Activity, Bundle)}.
+ * class may be used via pure composition:
+ *
+ * ```java
+ * public class SampleCompositionActivity extends Activity {
+ * private {@link BakuActivityTrait}<SampleCompositionActivity> mBaku;
+ *
+ * {@literal @}Override
+ * protected void onCreate(final Bundle savedInstanceState) {
+ * super.onCreate(savedInstanceState);
+ * setContentView(R.layout.my_activity_layout);
+ *
+ * mBaku = new {@link #BakuActivityMixin(Activity, Bundle)
+ * BakuActivityMixin}<>(this, savedInstanceState);
+ *
+ * // Example binding between "myDataRow" in Syncbase and myTextView in my_activity_layout.
+ * mBaku.{@link #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);
+ * }
+ *
+ * {@literal @}Override
+ * protected void onDestroy() {
+ * mBaku.{@link BakuActivityMixin#close() close}();
+ * super.onDestroy();
+ * }
+ * }
+ * ```
*
* @see io.v.baku.toolkit
*/
@@ -66,30 +94,13 @@
}
/**
- * Convenience constructor for compositional integration. Example usage:
- *
- * ```java
- * public class SampleCompositionActivity extends Activity {
- * private BakuActivityTrait<SampleCompositionActivity> mBaku;
- *
- * {@literal @}Override
- * protected void onCreate(final Bundle savedInstanceState) {
- * super.onCreate(savedInstanceState);
- * setContentView(R.layout.activity_hello);
- *
- * mBaku = new BakuActivityMixin<>(this, savedInstanceState);
- * }
- *
- * {@literal @}Override
- * protected void onDestroy() {
- * mBaku.close();
- * super.onDestroy();
- * }
- * }
- * ```
+ * Convenience constructor for compositional integration. For example usage,
+ * see the {@linkplain BakuActivityMixin class docs}.
*/
public BakuActivityMixin(final T context, final Bundle savedInstanceState) {
this(VAndroidContextMixin.withDefaults(context, savedInstanceState));
+ // We have to manage this VAndroidContextTrait since we created it.
+ mSubscriptions.add(Subscriptions.create(mVAndroidContextTrait::close));
}
@Override
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityTrait.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityTrait.java
index d5c77b2..cbccef4 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityTrait.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuActivityTrait.java
@@ -13,11 +13,40 @@
import io.v.baku.toolkit.syncbase.BakuTable;
import rx.subscriptions.CompositeSubscription;
-
+/**
+ * [Trait](package-summary.html#mixins) for activities with distributed UI state. This trait is
+ * implemented by {@link BakuActivityMixin}.
+ *
+ * For any UI widget that should have distributed state, the application should build data bindings
+ * by chaining methods from a {@link #binder()} call, binding shared data fields in the Syncbase
+ * distributed storage system to UI widget properties.
+ *
+ * Collection bindings (from vector data to list/recycler views) are similarly exposed through a
+ * {@link #collectionBinder() collectionBinder()} builder. Writes can be performed directly via
+ * {@link #getSyncbaseTable()}`.`{@link io.v.baku.toolkit.syncbase.BakuTable#put(java.lang.String,
+ * java.lang.Object) put(key, value)}. More information about data bindings is available in the
+ * {@link io.v.baku.toolkit.bind} package documentation.
+ *
+ * Implementations create a Syncbase table to use by default for data binding, and create and manage
+ * a default {@linkplain io.v.rx.syncbase.UserCloudSyncgroup global user-level cloud syncgroup} to
+ * sync distributed data across all instances of the application belonging to a user.
+ */
public interface BakuActivityTrait<T extends Activity> extends AutoCloseable {
VAndroidContextTrait<T> getVAndroidContextTrait();
BakuSyncbase getSyncbase();
BakuDb getSyncbaseDb();
+
+ /**
+ * Gets a wrapper for the Syncbase table, allowing for direct write operations. The wrapper
+ * includes {@link #onSyncError(Throwable)} as a default error handler for any actions that are
+ * not explicitly subscribed to, making write operations easier to use.
+ *
+ * Example usage:
+ *
+ * ```java
+ * getSyncbaseTable().put("myKey", myValue);
+ * ```
+ */
BakuTable getSyncbaseTable();
CompositeSubscription getSubscriptions();
String getSyncbaseTableName();
@@ -26,13 +55,40 @@
/**
* Exposes a default scalar data binding builder for this Activity. The returned builder may be
* freely customized; a new builder is returned for each call.
+ *
+ * Example usage:
+ *
+ * ```java
+ * 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);
+ * ```
*/
<U> SyncbaseBinding.Builder<U> binder();
/**
* Exposes a default collection data binding builder for this Activity. The returned builder may
* be freely customized; a new builder is returned for each call.
+ *
+ * Example usage:
+ *
+ * ```java
+ * collectionBinder()
+ * .{@link io.v.baku.toolkit.bind.CollectionBinding.Builder#onPrefix(String)
+ * onPrefix}("myListItems/")
+ * .{@link io.v.baku.toolkit.bind.PrefixBindingBuilder#type(Class) type}(String.class)
+ * .{@link io.v.baku.toolkit.bind.PrefixBindingBuilder#bindTo(int)
+ * bindTo}(R.id.myListView);
+ * ```
*/
CollectionBinding.Builder collectionBinder();
+
+ /**
+ * Unsubscribes all data bindings associated with this activity and releases the local Syncbase
+ * instance.
+ *
+ * @see BakuSyncbase#close()
+ */
void close();
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuAppCompatActivity.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuAppCompatActivity.java
index 85c0da8..c191aeb 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuAppCompatActivity.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/BakuAppCompatActivity.java
@@ -15,7 +15,26 @@
* A default integration with {@link BakuActivityTrait} extending
* {@link android.support.v7.app.AppCompatActivity}.
*
- * @see io.v.baku.toolkit
+ * Example usage:
+ *
+ * ```java
+ * public class SampleBakuActivity extends BakuAppCompatActivity {
+ * {@literal @}Override
+ * protected void onCreate(final Bundle savedInstanceState) {
+ * super.onCreate(savedInstanceState);
+ * setContentView(R.layout.my_activity_layout);
+ *
+ * // Example binding between "myDataRow" in Syncbase and myTextView in my_activity_layout.
+ * {@link #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);
+ * }
+ * }
+ * ```
+ *
+ * @see BakuActivity
*/
@Slf4j
public abstract class BakuAppCompatActivity
@@ -23,6 +42,10 @@
@Delegate
private BakuActivityTrait<AppCompatActivity> mBakuActivityTrait;
+ /**
+ * Instantiates the {@link BakuActivityTrait} implementation for this Activity. By default, this
+ * uses {@link BakuActivityMixin}.
+ */
protected BakuActivityTrait<AppCompatActivity> createBakuActivityTrait() {
return new BakuActivityMixin<>(this);
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VActivity.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VActivity.java
index 1164a0f..4b2eab3 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VActivity.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VActivity.java
@@ -12,11 +12,17 @@
/**
* A default integration with {@link VAndroidContextTrait} extending {@link Activity}.
+ *
+ * @see VAppCompatActivity
*/
public abstract class VActivity extends Activity implements VAndroidContextTrait<Activity> {
@Delegate
private VAndroidContextTrait<Activity> mVAndroidContextTrait;
+ /**
+ * Instantiates the {@link VAndroidContextTrait} implementation for this Activity. By default,
+ * this uses {@link VAndroidContextMixin#withDefaults(Activity, Bundle)}.
+ */
protected VAndroidContextTrait<Activity> createVActivityTrait(final Bundle savedInstanceState) {
return VAndroidContextMixin.withDefaults(this, savedInstanceState);
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextMixin.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextMixin.java
index 03a3ad4..f84b13c 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextMixin.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextMixin.java
@@ -27,20 +27,12 @@
import lombok.extern.slf4j.Slf4j;
/**
- * Android context mix-in incorporating common Vanadium utilities. These include:
- * <ul>
- * <li>Vanadium initialization during {@code onCreate}; context available via
- * {@code getVContext}</li>
- * <li>Blessings management, available via {@link BlessingsProvider#getRxBlessings()
- * getBlessingsProvider().getRxBlessings()}. Upon {@code subscribe}, blessings are refreshed from
- * the {@code BlessingsManager} or sought from the {@code BlessingsProvider} (by default, the
- * Vanadium {@link io.v.android.libs.security.BlessingsManager}).</li>
- * </ul>
- * Default activity extensions incorporating this mix-in are available:
- * <ul>
- * <li>{@link VActivity} (extends {@link Activity})</li>
- * <li>{@link VAppCompatActivity} (extends {@link android.support.v7.app.AppCompatActivity})</li>
- * </ul>
+ * Backing [mix-in](package-summary.html#mixins) for {@link VAndroidContextTrait}. Default
+ * `Activity` subclasses incorporating this mix-in are available:
+ *
+ * * {@link VActivity} (`extends {@link Activity}`)
+ * * {@link VAppCompatActivity} (`extends {@link android.support.v7.app.AppCompatActivity}`)
+ *
* Since Java doesn't actually support multiple inheritance, clients requiring custom inheritance
* hierarchies will need to wire in manually, like any of the examples above.
*/
@@ -115,6 +107,18 @@
}
}
+ /**
+ * Creates a `VAndroidContextMixin` with default settings. Default settings include:
+ *
+ * * {@link ErrorReporter}: {@link ErrorReporterFragment}
+ * * {@link BlessingsProvider}: {@link BlessingsManagerBlessingsProvider}
+ *
+ * Furthermore, if the apk is built as {@linkplain DebugUtils#isApkDebug(Context) debug}, a
+ * {@linkplain DebugFragment debug menu} is included.
+ *
+ * The signature of this method is intended to be called from {@link Activity#onCreate(Bundle)}
+ * or similar methods.
+ */
public static <T extends Activity> VAndroidContextMixin<T> withDefaults(
final T activity, final Bundle savedInstanceState) {
final FragmentManager mgr = activity.getFragmentManager();
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextTrait.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextTrait.java
index 63eaaf4..f2558e8 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextTrait.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAndroidContextTrait.java
@@ -4,17 +4,43 @@
package io.v.baku.toolkit;
+import android.app.Activity;
import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Bundle;
import io.v.baku.toolkit.blessings.BlessingsProvider;
import io.v.v23.context.VContext;
+/**
+ * [Trait](package-summary.html#mixins) for Vanadium Android {@link Context}s (Activities, Services,
+ * Applications, etc.). This trait is implemented by {@link VAndroidContextMixin}.
+ *
+ * Common Vanadium tasks encapsulated by this trait include:
+ *
+ * * Vanadium lifecycle management. Implementations initialize a Vanadium context on instantiation,
+ * presumably during {@link Activity#onCreate(Bundle) onCreate}. The Vanadium context is then
+ * available via {@link #getVContext()}. It is cancelled on {@link #close()}.
+ * * Blessings management, available via {@link BlessingsProvider#getRxBlessings()
+ * getBlessingsProvider().getRxBlessings()}. Upon `subscribe`, blessings are refreshed from the
+ * {@link BlessingsProvider}. The default `BlessingsProvider` furnished by
+ * {@link VAndroidContextMixin#withDefaults(Activity, Bundle)} is the Vanadium
+ * {@link io.v.android.libs.security.BlessingsManager}.
+ */
public interface VAndroidContextTrait<T extends Context> extends AutoCloseable {
+ /**
+ * Shared preference key for storing Vanadium options.
+ * @see VOptionPreferenceUtils#getOptionsFromPreferences(SharedPreferences)
+ */
String VANADIUM_OPTIONS_SHARED_PREFS = "VanadiumOptions";
T getAndroidContext();
BlessingsProvider getBlessingsProvider();
ErrorReporter getErrorReporter();
VContext getVContext();
+
+ /**
+ * Cleans up ({@linkplain VContext#cancel() cancels}) the Vanadium context.
+ */
void close();
}
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAppCompatActivity.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAppCompatActivity.java
index f5b453e..5c82ec4 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAppCompatActivity.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/VAppCompatActivity.java
@@ -4,6 +4,7 @@
package io.v.baku.toolkit;
+import android.app.Activity;
import android.os.Bundle;
import android.os.PersistableBundle;
import android.support.v7.app.AppCompatActivity;
@@ -14,6 +15,8 @@
/**
* A default integration with {@link VAndroidContextTrait} extending
* {@link android.support.v7.app.AppCompatActivity}.
+ *
+ * @see VActivity
*/
@Slf4j
public abstract class VAppCompatActivity extends AppCompatActivity
@@ -21,6 +24,10 @@
@Delegate
private VAndroidContextTrait<AppCompatActivity> mVAndroidContextTrait;
+ /**
+ * Instantiates the {@link VAndroidContextTrait} implementation for this Activity. By default,
+ * this uses {@link VAndroidContextMixin#withDefaults(Activity, Bundle)}.
+ */
protected VAndroidContextTrait<AppCompatActivity> createVActivityTrait(
final Bundle savedInstanceState) {
return VAndroidContextMixin.withDefaults(this, savedInstanceState);
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/package-info.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/package-info.java
index fd8ac26..f431a02 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/package-info.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/bind/package-info.java
@@ -3,10 +3,14 @@
// license that can be found in the LICENSE file.
/**
- * These classes provide bindings between Android widgets and Syncbase data. For the reasons
- * outlined in {@link io.v.rx.syncbase}, Vanadium state distribution with Syncbase would ideally be
- * done with pure FRP [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel),
- * with distributed state elements modeled in Syncbase.
+ * These classes provide bindings between Android widgets and Syncbase data. Most functionality is
+ * most easily accessed through access vectors in {@link io.v.baku.toolkit} rather than
+ * instantiating directly from this package.
+ *
+ * For the reasons outlined in {@link io.v.rx.syncbase}, Vanadium state distribution with Syncbase
+ * would ideally be done with pure FRP [MVVM]
+ * (https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel), with distributed state
+ * elements modeled in Syncbase.
*
* 
*
diff --git a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/debug/DebugFragment.java b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/debug/DebugFragment.java
index 67721ab..5322e26 100644
--- a/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/debug/DebugFragment.java
+++ b/baku-toolkit/lib/src/main/java/io/v/baku/toolkit/debug/DebugFragment.java
@@ -5,6 +5,7 @@
package io.v.baku.toolkit.debug;
import android.app.Fragment;
+import android.content.Context;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuInflater;
@@ -13,6 +14,14 @@
import io.v.baku.toolkit.R;
import lombok.extern.slf4j.Slf4j;
+/**
+ * Fragment containing a debug menu for common Vanadium/Syncbase debug actions. These actions
+ * include:
+ *
+ * * {@linkplain DebugLogDialogFragment Change log level and view logcat}
+ * * {@linkplain DebugUtils#clearAppData(Context) Clear app data}
+ * * {@linkplain DebugUtils#killProcess(Context) Kill process}
+ */
@Slf4j
public class DebugFragment extends Fragment {
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 9f1ecf4..1dc9ffd 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
@@ -6,36 +6,7 @@
* This package is the entry point into the Baku Toolkit. The easiest way for an application to take
* advantage of Baku is for its activities with distributed state to inherit from
* {@link io.v.baku.toolkit.BakuActivity} (or {@link io.v.baku.toolkit.BakuAppCompatActivity}; see
- * {@link io.v.baku.toolkit.BakuActivityMixin} for custom inheritance trees). Then, for any UI
- * widget that should have distributed state, the client application should build data bindings by
- * chaining methods from a {@link io.v.baku.toolkit.BakuActivityTrait#binder() binder()} call,
- * binding shared data fields in the Syncbase distributed storage system to UI widget properties.
- * For [example](https://goo.gl/P0Ag9a), the following binds a data key named `"text"` to the text
- * of a {@link android.widget.TextView} with ID `textView`:
- *
- * ```java
- * {@literal @}Override
- * protected void onCreate(final Bundle savedInstanceState) {
- * super.onCreate(savedInstanceState);
- * setContentView(R.layout.my_activity_layout);
- *
- * {@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);
- * }
- * }
- * ```
- *
- * Collection bindings (from vector data to list/recycler views) are similarly exposed through a
- * {@link io.v.baku.toolkit.BakuActivityTrait#collectionBinder() collectionBinder()} builder. Writes
- * can be performed directly via {@link io.v.baku.toolkit.syncbase.BakuTable#put(java.lang.String,
- * java.lang.Object) getSyncbaseTable().put(key, value)}. More information about data bindings is
- * available in the {@link io.v.baku.toolkit.bind} package documentation.
- *
- * The Baku Toolkit creates a Syncbase table to use by default for data binding, and creates and
- * manages a default {@linkplain io.v.rx.syncbase.UserCloudSyncgroup global user-level cloud
- * syncgroup} to sync distributed data across all instances of the application belonging to a user.
+ * [Mix-ins](#mixins) for other usage options).
*
* Baku components are built in layers bundling common sets of functionality. This allows
* application developers the flexibility to selectively interact with APIs when they need to work
@@ -43,5 +14,38 @@
*
* Sample code is available in the [baku projects repo]
* (https://vanadium.googlesource.com/release.projects.baku).
+ *
+ * ## <a name="mixins"></a>Traits and Mix-ins
+ *
+ * * {@link io.v.baku.toolkit.BakuActivityTrait} / {@link io.v.baku.toolkit.BakuActivityMixin}
+ * * {@link io.v.baku.toolkit.VAndroidContextTrait} / {@link io.v.baku.toolkit.VAndroidContextMixin}
+ *
+ * Android Activity classes can have different inheritance hierarchies depending on whether they are
+ * edge-version {@link android.app.Activity}s or support-library
+ * {@link android.support.v7.app.AppCompatActivity}s. Meanwhile the common code to support
+ * {@link io.v.baku.toolkit.BakuActivity}s and {@link io.v.baku.toolkit.VActivity}s is most easily
+ * used if included as superclass methods of the application Activity. Moreover, it really is an
+ * "is-a" relationship. As such, multiple inheritance would be the natural way to arrange these
+ * classes, but Java does not allow this.
+ *
+ * To still offer the same ease of use to client applications, we approximate [Scala-style mix-ins]
+ * (http://docs.scala-lang.org/tutorials/tour/mixin-class-composition.html) by using "trait"
+ * interfaces, "mix-in" classes, and tying them to Activity inheritance hierarchies by using Lombok
+ * [`@Delegate`](https://projectlombok.org/features/experimental/Delegate.html) annotations. The
+ * trait interfaces define the method signatures expected of `BakuActivity`s and `VActivity`s while
+ * the mix-in classes define their implementations and associated private state. These mix-in
+ * classes are included as `@Delegate`-annotated member fields of the `BakuActivity` and `VActivity`
+ * classes, giving those classes implementations of {@link io.v.baku.toolkit.BakuActivityTrait} and
+ * {@link io.v.baku.toolkit.VAndroidContextTrait} methods and allowing those classes to `implements`
+ * those interfaces.
+ *
+ * Ideally `BakuActivityTrait`/`Mixin` would `extends VAndroidContextTrait`/`Mixin` in a secondary
+ * inheritance ancestry, but the `@Delegate` annotation is not powerful enough to support nested
+ * delegates, and that relation is instead expressed through pure composition, via a
+ * {@link io.v.baku.toolkit.BakuActivityTrait#getVAndroidContextTrait() getVAndroidContextTrait()}
+ * method.
+ *
+ * Applications can also wire these mix-ins into custom inheritance hierarchies by following the
+ * example of [`BakuActivity`](https://goo.gl/e2Bkc2) and/or [`VActivity`](https://goo.gl/obS1qj).
*/
package io.v.baku.toolkit;
\ No newline at end of file
diff --git a/baku-toolkit/lib/src/main/java/overview.md b/baku-toolkit/lib/src/main/java/overview.md
index 97ef69b..bd297bf 100644
--- a/baku-toolkit/lib/src/main/java/overview.md
+++ b/baku-toolkit/lib/src/main/java/overview.md
@@ -2,7 +2,7 @@
development of applications with distributed user interfaces.
## Getting Started
-To get started, see the {@link io.v.baku.toolkit} package docs.
+To get started, see {@link io.v.baku.toolkit.BakuActivity}.
## Usage
The Baku Android Toolkit library is available from JCenter and Maven
