feat(docs): Initial pass at API references for gh-pages

lib/attributes/attribute-collection.js

@@ -1,8 +1,8 @@
 import Attribute from './attribute';
 import Matcher from './matcher';
 
-/*
-Public: Collection attributes provide basic support for one-to-many relationships.
+/**
+Collection attributes provide basic support for one-to-many relationships.
 For example, Threads in N1 have a collection of Labels or Folders.
 
 When Collection attributes are marked as `queryable`, the DatabaseStore
@@ -92,7 +92,9 @@ export default class AttributeCollection extends Attribute {
     return objs;
   }
 
-  // Public: Returns a {Matcher} for objects containing the provided value.
+  /**
+  @returns {Matcher} - Matcher for objects containing the provided value.
+  */
   contains(val) {
     this._assertPresentAndQueryable('contains', val);
     return new Matcher(this, 'contains', val);

lib/attributes/attribute-joined-data.js

@@ -2,8 +2,8 @@ import Attribute from './attribute';
 
 const NullPlaceholder = "!NULLVALUE!";
 
-/*
-Public: Joined Data attributes allow you to store certain attributes of an
+/**
+Joined Data attributes allow you to store certain attributes of an
 object in a separate table in the database. We use this attribute
 type for Message bodies. Storing message bodies, which can be very
 large, in a separate table allows us to make queries on message

lib/attributes/attribute-object.js

@@ -1,7 +1,7 @@
 import Attribute from './attribute';
 
 /**
-An object that can be cast to `itemClass`
+The value of this attribute is always an object that can be cast to `itemClass`
 */
 export default class AttributeObject extends Attribute {
   constructor({modelKey, jsonKey, itemClass, queryable}) {

lib/attributes/attribute-string.js

@@ -4,8 +4,8 @@ import Matcher from './matcher';
 /**
 The value of this attribute is always a string or `null`.
 
-String attributes can be queries using `equal`, `not`, and `startsWith`. Matching on
-`greaterThan` and `lessThan` is not supported.
+String attributes can be queries using `equal`, `not`, and `startsWith`.
+Matching on `greaterThan` and `lessThan` is not supported.
 */
 export default class AttributeString extends Attribute {
   toJSON(val) {

lib/attributes/matcher.js

@@ -8,37 +8,37 @@ const singleQuoteEscapeSequence = "''";
 const doubleQuoteEscapeSequence = '""';
 
 
-/*
-Public: The Matcher class encapsulates a particular comparison clause on an {Attribute}.
+/**
+The Matcher class encapsulates a particular comparison clause on an {@link Attribute}.
 Matchers can evaluate whether or not an object matches them, and also compose
-SQL clauses for the DatabaseStore. Each matcher has a reference to a model
-attribute, a comparator and a value.
+SQL clauses for the {@link DatabaseStore}. Each matcher has a reference to a model
+attribute, a comparator and a value. This class is heavily inspired by
+NSPredicate on Mac OS X / CoreData.
 
-```coffee
+```js
 
 // Retrieving Matchers
 
-isUnread = Thread.attributes.unread.equal(true)
+const isUnread = Thread.attributes.unread.equal(true);
 
-hasLabel = Thread.attributes.categories.contains('label-id-123')
+const hasLabel = Thread.attributes.categories.contains('label-id-123');
 
 // Using Matchers in Database Queries
 
-db.findAll(Thread).where(isUnread)...
+const db.findAll(Thread).where(isUnread)...
 
 // Using Matchers to test Models
 
-threadA = new Thread(unread: true)
-threadB = new Thread(unread: false)
+const threadA = new Thread({unread: true})
+const threadB = new Thread({unread: false})
 
 isUnread.evaluate(threadA)
 // => true
+
 isUnread.evaluate(threadB)
 // => false
 
 ```
-
-Section: Database
 */
 class Matcher {
   constructor(attr, comparator, val) {
@@ -161,6 +161,10 @@ class Matcher {
 
 Matcher.muid = 0
 
+/**
+This subclass is publicly exposed as Matcher.Or.
+@private
+*/
 class OrCompositeMatcher extends Matcher {
   constructor(children) {
     super();
@@ -196,6 +200,10 @@ class OrCompositeMatcher extends Matcher {
   }
 }
 
+/**
+This subclass is publicly exposed as Matcher.And.
+@private
+*/
 class AndCompositeMatcher extends Matcher {
   constructor(children) {
     super();
@@ -231,6 +239,10 @@ class AndCompositeMatcher extends Matcher {
   }
 }
 
+/**
+This subclass is publicly exposed as Matcher.Not.
+@private
+*/
 class NotCompositeMatcher extends AndCompositeMatcher {
   whereSQL(klass) {
     return `NOT (${super.whereSQL(klass)})`;

lib/attributes/sort-order.js

@@ -1,13 +1,14 @@
-/*
-Public: Represents a particular sort direction on a particular column. You should not
-instantiate SortOrders manually. Instead, call {Attribute::ascending} or
-{Attribute::descending} to obtain a sort order instance:
+/**
+Represents a particular sort direction on a particular column. You should not
+instantiate SortOrders manually. Instead, call {@link Attribute.ascending} or
+{@link Attribute.descending} to obtain a sort order instance:
 
-```coffee
+```js
 db.findBy(Message)
   .where({threadId: threadId, draft: false})
-  .order(Message.attributes.date.descending()).then (messages) ->
+  .order(Message.attributes.date.descending()).then((messages) {
 
+});
 ```
 
 Section: Database

lib/database-change-record.js

@@ -1,10 +1,13 @@
 import {registeredObjectReplacer, registeredObjectReviver} from './utils';
 
 /**
-DatabaseChangeRecord is the object emitted from the DatabaseStore when it triggers.
-The DatabaseChangeRecord contains information about what type of model changed,
-and references to the new model values. All mutations to the database produce these
-change records.
+An RxDB database emits DatabaseChangeRecord objects once a transaction has completed.
+The change record contains a copy of the model(s) that were modified, the type of
+modification (persist / destroy) and the model class.
+
+DatabaseChangeRecords can be serialized to JSON and RxDB transparently bridges
+them between windows of Electron applications. Change records of the same type
+and model class can also be merged.
 */
 export default class DatabaseChangeRecord {
 

lib/database-setup-query-builder.js

@@ -6,9 +6,10 @@ import Attributes from './attributes';
 const {AttributeCollection, AttributeJoinedData} = Attributes;
 
 /**
-The DatabaseConnection dispatches queries to the Browser process via IPC and listens
-for results. It maintains a hash of `_queryRecords` representing queries that are
-currently running and fires promise callbacks when complete.
+The factory methods in this class assemble SQL queries that build Model
+tables based on their attribute schema.
+
+@private
 */
 export default class DatabaseSetupQueryBuilder {