Merge pull request #402 from realm/sk-api-docs

API doc updates

docs/object.js

@@ -0,0 +1,32 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2016 Realm Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Realm objects will automatically inherit from this class unless a {@link Realm~ObjectClass}
+ * was specified that does **not** inherit from this class.
+ * @memberof Realm
+ * @since 0.12.0
+ */
+class Object {
+    /**
+     * Checks if this object has not been deleted and is part of a valid Realm.
+     * @returns {boolean} indicating if the object can be safely accessed.
+     * @since 0.12.0
+     */
+    isValid() {}
+}

docs/realm.js

@@ -23,6 +23,30 @@
  * ```
  */
 class Realm {
+    /**
+     * The path to the file where this Realm is stored.
+     * @type {string}
+     * @readonly
+     * @since 0.12.0
+     */
+    get path() {}
+
+    /**
+     * Indicates if this Realm was opened as read-only.
+     * @type {boolean}
+     * @readonly
+     * @since 0.12.0
+     */
+    get readOnly() {}
+
+   /**
+    * The current schema version of this Realm.
+    * @type {number}
+    * @readonly
+    * @since 0.12.0
+    */
+    get schemaVersion() {}
+
     /**
      * 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
@@ -126,8 +150,15 @@ Realm.defaultPath;
  * @type {Object}
  * @property {ArrayBuffer|ArrayBufferView} [encryptionKey] - The 512-bit (64-byte) encryption
  *   key used to encrypt and decrypt all data in the Realm.
+ * @property {function(Realm, Realm)} [migration] - The function to run if a migration is needed.
+ *   This function should provide all the logic for converting data models from previous schemas
+ *   to the new schema.
+ *   This function takes two arguments:
+ *   - `oldRealm` - The Realm before migration is performed.
+ *   - `newRealm` - The Realm that uses the latest `schema`, which should be modified as necessary.
  * @property {string} [path={@link Realm.defaultPath}] - The path to the file where the
  *   Realm database should be stored.
+ * @property {boolean} [readOnly=false] - Specifies if this Realm should be opened as read-only.
  * @property {Array<Realm~ObjectClass|Realm~ObjectSchema>} [schema] - Specifies all the
  *   object types in this Realm. **Required** when first creating a Realm at this `path`.
  * @property {number} [schemaVersion] - **Required** (and must be incremented) after
@@ -136,7 +167,8 @@ Realm.defaultPath;
 
 /**
  * Realm objects will inherit methods, getters, and setters from the `prototype` of this
- * constructor.
+ * constructor. It is **highly recommended** that this constructor inherit from
+ * {@link Realm.Object}.
  * @typedef Realm~ObjectClass
  * @type {Class}
  * @property {Realm~ObjectSchema} schema - Static property specifying object schema information.