Merge pull request #228 from realm/sk-docs

API documentation

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "vendor/PEGTL"]
 	path = vendor/PEGTL
 	url = https://github.com/ColinH/PEGTL.git
+[submodule "docs/jsdoc-template"]
+	path = docs/jsdoc-template
+	url = https://github.com/realm/realm-jsdoc.git

docs/.gitignore

@@ -0,0 +1 @@
+output/

docs/conf.json

@@ -0,0 +1,22 @@
+{
+  "opts": {
+    "destination": "docs/output",
+    "readme": "README.md",
+    "recurse": true,
+    "template": "docs/jsdoc-template/template"
+  },
+  "source": {
+    "include": ["docs"],
+    "exclude": ["docs/jsdoc-template", "docs/output"]
+  },
+  "tags": {
+    "allowUnknownTags": false
+  },
+  "plugins": ["plugins/markdown"],
+  "templates": {
+    "cleverLinks": true,
+    "default": {
+      "outputSourceFiles": false
+    }
+  }
+}

docs/jsdoc-template

@@ -0,0 +1 @@
+Subproject commit f21b8a34130c287429ba1e8f120e3645b45766c8

docs/list.js

@@ -0,0 +1,64 @@
+/* Copyright 2016 Realm Inc - All Rights Reserved
+ * Proprietary and Confidential
+ */
+
+
+/**
+ * Instances of this class will be returned when accessing object properties whose type is `"list"`
+ * (see {@linkplain Realm~ObjectSchemaProperty ObjectSchemaProperty}).
+ * The objects contained in a list are accessible through its index properties and may only be
+ * modified inside a {@linkplain Realm#write write} transaction.
+ * @memberof Realm
+ */
+class List {
+    /**
+     * The number of objects in the list.
+     * @type {number}
+     * @readonly
+     */
+    get length() {}
+
+    /**
+     * Create a frozen snapshot of the list. This means changes to the list will not be
+     * reflected in the results returned by this method. However, deleted objects will become
+     * `null` at their respective indices.
+     * @returns {Realm.Results} which will **not** live update.
+     */
+    snapshot() {}
+
+    /**
+     * Remove the **first** object from the list and return it.
+     * @throws {Error} If not inside a write transaction.
+     * @returns {Realm.Object|undefined} if the list is empty.
+     */
+    shift() {}
+
+    /**
+     * Remove the **last** object from the list and return it.
+     * @throws {Error} If not inside a write transaction.
+     * @returns {Realm.Object|undefined} if the list is empty.
+     */
+    pop() {}
+
+    /**
+     * Add one or more objects to the _end_ of the list.
+     * @param {...Realm.Object} object - Each object’s type must match
+     *   {@linkcode Realm~ObjectSchemaProperty objectType} specified in the schema.
+     * @throws {TypeError} If an `object` is of the wrong type.
+     * @throws {Error} If not inside a write transaction.
+     * @returns {number} equal to the new {@link Realm.List#length length} of the list
+     *   after adding objects.
+     */
+    push(...object) {}
+
+    /**
+     * Add one or more objects to the _beginning_ of the list.
+     * @param {...Realm.Object} object - Each object’s type must match
+     *   {@linkcode Realm~ObjectSchemaProperty objectType} specified in the schema.
+     * @throws {TypeError} If an `object` is of the wrong type.
+     * @throws {Error} If not inside a write transaction.
+     * @returns {number} equal to the new {@link Realm.List#length length} of the list
+     *   after adding objects.
+     */
+    unshift(...object) {}
+}

docs/realm.js

@@ -0,0 +1,164 @@
+/* Copyright 2016 Realm Inc - All Rights Reserved
+ * Proprietary and Confidential
+ */
+
+/**
+ * A Realm instance represents a Realm database.
+ * ```js
+ * const Realm = require('realm');
+ * ```
+ */
+class Realm {
+    /**
+     * Create a new `Realm` instance using the provided `config`. If a Realm does not yet exist
+     * at `config.path` (or {@link Realm.defaultPath} if not provided), then this constructor
+     * will create it with the provided `config.schema` (which is _required_ in this case).
+     * Otherwise, the instance will access the existing realm from the file at that path.
+     * In this case, `config.schema` is _optional_ or not have changed, unless
+     * `config.schemaVersion` is incremented, in which case the realm will be automatically
+     * migrated to use the new schema.
+     * @param {Realm~Configuration} [config] - **Required** when first creating the Realm.
+     */
+    constructor(config) {}
+
+    /**
+     * Create a new Realm object of the given type and with the specified properties.
+     * @param {string} type - The type of object as specified by its `name` in the
+     *   {@link Realm~ObjectSchema ObjectSchema} definition.
+     * @param {Object} properties - Property values for all required properties without a
+     *   default value.
+     * @param {boolean} [update=false] - Signals that an existing object with matching primary key
+     *   should be updated. Only the primary key property and properties which should be updated
+     *   need to be specified. All missing property values will remain unchanged.
+     * @returns {Realm.Object}
+     */
+    create(type, properties, update) {}
+
+    /**
+     * Deletes the provided Realm object, or each one inside the provided collection.
+     * @param {Realm.Object|Realm.Object[]|Realm.List|Realm.Results} object
+     */
+    delete(object) {}
+
+    /**
+     * **WARNING:** This will delete **all** objects in the Realm!
+     */
+    deleteAll() {}
+
+    /**
+     * Returns all objects of the given `type` in the Realm, optionally filtered by the provided
+     * `query`.
+     * ```js
+     * let merlots = realm.objects('Wine', 'varietal == "Merlot" && vintage <= $0', maxYear);
+     * ```
+     * @param {string} type - The type of object as specified by its `name` in the
+     *   {@link Realm~ObjectSchema ObjectSchema} definition.
+     * @param {string} [query] - Query used to filter results.
+     * @param {...any} [arg] - Each subsequent argument is used by the placeholders
+     *   (e.g. `$0`, `$1`, `$2`, …) in the query.
+     * @throws {Error} If type, query, or any other argument passed into this method is invalid.
+     * @returns {Realm.Results}
+     */
+    objects(type, query, ...arg) {}
+
+    /**
+     * Add a listener `callback` for the specified event `name`.
+     * @param {string} name - The name of event that should cause the callback to be called.
+     *   _Currently, only the "change" event supported_.
+     * @param {function(Realm, string)} callback - Function to be called when the event occurs.
+     *   Each callback will only be called once per event, regardless of the number of times
+     *   it was added.
+     * @throws {Error} If an invalid event `name` is supplied, or if `callback` is not a function.
+     */
+    addListener(name, callback) {}
+
+   /**
+    * Remove the listener `callback` for the specfied event `name`.
+    * @param {string} name - The event name.
+    *   _Currently, only the "change" event supported_.
+    * @param {function(Realm, string)} callback - Function that was previously added as a
+    *   listener for this event through the {@link Realm#addListener addListener} method.
+    * @throws {Error} If an invalid event `name` is supplied, or if `callback` is not a function.
+    */
+    removeListener(name, callback) {}
+
+   /**
+    * Remove all event listeners (restricted to the event `name`, if provided).
+    * @param {string} [name] - The name of the event whose listeners should be removed.
+    *   _Currently, only the "change" event supported_.
+    * @throws {Error} When invalid event `name` is supplied
+    */
+    removeAllListeners(name) {}
+
+   /**
+    * Synchronously call the provided `callback` inside a write transaction.
+    * @param {function()} callback
+    */
+    write(callback) {}
+}
+
+/**
+ * The default path where to create and access the Realm file.
+ * @type {string}
+ */
+Realm.defaultPath;
+
+/**
+ * This describes the different options used to create a {@link Realm} instance.
+ * @typedef Realm~Configuration
+ * @type {Object}
+ * @property {string} [path={@link Realm.defaultPath}] - The path to the file where the
+ *   Realm database should be stored.
+ * @property {Realm~ObjectSchema[]} [schema] - Specifies all the object types in the realm.
+ *   **Required** when first creating realm at this `path`.
+ * @property {number} [schemaVersion] - **Required** (and must be incremented) after
+ *   changing the `schema`.
+ */
+
+/**
+ * @typedef Realm~ObjectSchema
+ * @type {Object}
+ * @property {string} name - Represents the object type.
+ * @property {string} [primaryKey] - The name of a `"string"` or `"int"` property
+ *   that must be unique across all objects of this type within the same Realm.
+ * @property {Object<string, (Realm~PropertyType|Realm~ObjectSchemaProperty)>} properties -
+ *   An object where the keys are property names and the values represent the property type.
+ */
+
+/**
+ * @typedef Realm~ObjectSchemaProperty
+ * @type {Object}
+ * @property {Realm~PropertyType} type - The type of this property.
+ * @property {string} [objectType] - **Required**  when `type` is `"list"`, and must match the
+ *   type of an object in the same schema.
+ * @property {any} [default] - The default value for this property on creation when not
+ *   otherwise specified.
+ * @property {boolean} [optional] - Signals if this property may be assigned `null` or `undefined`.
+ */
+
+/**
+ * A property type may be specified as one of the standard builtin types, or as an object type
+ * inside the same schema.
+ * @typedef Realm~PropertyType
+ * @type {("bool"|"int"|"float"|"double"|"string"|"date"|"data"|"list"|"<ObjectType>")}
+ * @property {boolean} "bool" - Property value may either be `true` or `false`.
+ * @property {number} "int" - Property may be assigned any number, but will be stored as a
+ *   round integer, meaning anything after the decimal will be truncated.
+ * @property {number} "float" - Property may be assigned any number, but will be stored as a
+ *   `float`, which may result in a loss of precision.
+ * @property {number} "double" - Property may be assigned any number, and will have no loss
+ *   of precision.
+ * @property {string} "string" - Property value may be any arbitrary string.
+ * @property {Date} "date" - Property may be assigned any `Date` instance, but will be stored
+ *   with second-level precision (a fix for this is in progress).
+ * @property {ArrayBuffer} "data" - Property may either be assigned an `ArrayBuffer`
+ *   or `ArrayBufferView` (e.g. `DataView`, `Int8Array`, `Float32Array`, etc.) instance,
+ *   but will always be returned as an `ArrayBuffer`.
+ * @property {Realm.List} "list" - Property may be assigned any ordered collection
+ *   (e.g. `Array`, {@link Realm.List}, {@link Realm.Results}) of objects all matching the
+ *   `objectType` specified in the {@link Realm~ObjectSchemaProperty ObjectSchemaProperty}.
+ * @property {Realm.Object} "<ObjectType>" - A string that matches the `name` of an object in the
+ *   same schema (see {@link Realm~ObjectSchema ObjectSchema}) – this property may be assigned
+ *   any object of this type from inside the same Realm, and will always be _optional_
+ *   (meaning it may also be assigned `null` or `undefined`).
+ */

docs/results.js

@@ -0,0 +1,36 @@
+/* Copyright 2016 Realm Inc - All Rights Reserved
+ * Proprietary and Confidential
+ */
+
+
+/**
+ * Instances of this class are typically **live** collections returned by
+ * {@link Realm#objects objects()} that will update as new objects are either
+ * added to or deleted from the Realm that match the underlying query. Results returned by
+ * {@link Realm.Results#snapshot snapshot()}, however, are will **not** live update.
+ * @memberof Realm
+ */
+class Results {
+   /**
+    * The number of objects in the results.
+    * @type {number}
+    * @readonly
+    */
+   get length() {}
+
+    /**
+     * Create a frozen snapshot of the list. This means changes to the list will not be
+     * reflected in the results returned by this method. However, deleted objects will become
+     * `null` at their respective indices.
+     * @returns {Realm.Results} which will **not** live update.
+     */
+    snapshot() {}
+
+    /**
+     * Modifies this collection to be sorted by the provided property of each object.
+     * @param {string} name - The property name to sort results by.
+     * @param {boolean} [ascending=true]
+     * @throws {Error} If the specified property does not exist.
+     */
+    sortByProperty(name, ascending) {}
+}

package.json

@@ -13,7 +13,11 @@
     "RealmJS.xcodeproj"
   ],
   "scripts": {
+    "jsdoc": "rm -rf docs/output && jsdoc -c docs/conf.json",
     "test": "scripts/test.sh",
     "prepublish": "scripts/prepublish.sh"
+  },
+  "devDependencies": {
+    "jsdoc": "^3.4.0"
   }
 }

scripts/test.sh

@@ -69,6 +69,9 @@ cleanup
 trap cleanup EXIT
 
 case "$TARGET" in
+"jsdoc")
+  npm run jsdoc
+  ;;
 "realmjs")
   xcodebuild -scheme RealmJS -configuration "$CONFIGURATION" -sdk iphonesimulator $DESTINATION build test
   ;;