From b63dfd1c04faa150eb29feff97a04586564d444a Mon Sep 17 00:00:00 2001 From: Scott Kyle Date: Fri, 29 Jan 2016 00:46:25 -0800 Subject: [PATCH 1/3] API documentation This includes the initial draft of API docs that are generated by JSDoc using a template that was greatly improved to best handle this content. --- .gitmodules | 3 + docs/.gitignore | 1 + docs/conf.json | 22 ++++++ docs/jsdoc-template | 1 + docs/list.js | 65 ++++++++++++++++++ docs/realm.js | 164 ++++++++++++++++++++++++++++++++++++++++++++ docs/results.js | 36 ++++++++++ package.json | 4 ++ 8 files changed, 296 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/conf.json create mode 160000 docs/jsdoc-template create mode 100644 docs/list.js create mode 100644 docs/realm.js create mode 100644 docs/results.js diff --git a/.gitmodules b/.gitmodules index 483e2694..c5601328 100644 --- a/.gitmodules +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..ea1472ec --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +output/ diff --git a/docs/conf.json b/docs/conf.json new file mode 100644 index 00000000..5551074d --- /dev/null +++ b/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 + } + } +} diff --git a/docs/jsdoc-template b/docs/jsdoc-template new file mode 160000 index 00000000..f21b8a34 --- /dev/null +++ b/docs/jsdoc-template @@ -0,0 +1 @@ +Subproject commit f21b8a34130c287429ba1e8f120e3645b45766c8 diff --git a/docs/list.js b/docs/list.js new file mode 100644 index 00000000..f199475f --- /dev/null +++ b/docs/list.js @@ -0,0 +1,65 @@ +/* Copyright 2016 Realm Inc - All Rights Reserved + * Proprietary and Confidential + */ + + +/** + * Instances of this class (herein referred to as “lists”) 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) {} +} \ No newline at end of file diff --git a/docs/realm.js b/docs/realm.js new file mode 100644 index 00000000..0769ccb6 --- /dev/null +++ b/docs/realm.js @@ -0,0 +1,164 @@ +/* Copyright 2016 Realm Inc - All Rights Reserved + * Proprietary and Confidential + */ + +/** + * A Realm instance (also referred to as a realm) 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} 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"|"")} + * @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} "" - 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`). + */ diff --git a/docs/results.js b/docs/results.js new file mode 100644 index 00000000..8db20261 --- /dev/null +++ b/docs/results.js @@ -0,0 +1,36 @@ +/* Copyright 2016 Realm Inc - All Rights Reserved + * Proprietary and Confidential + */ + + +/** + * Instances of this class (herein referred to as “results”) 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) {} +} diff --git a/package.json b/package.json index e8c7fc6d..570e29d6 100644 --- a/package.json +++ b/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" } } From ea2c119f4d5fcfa404ed2739be60deae1654f07d Mon Sep 17 00:00:00 2001 From: Scott Kyle Date: Mon, 8 Feb 2016 16:41:37 -0800 Subject: [PATCH 2/3] Remove some API doc qualifiers --- docs/list.js | 3 +-- docs/realm.js | 2 +- docs/results.js | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/list.js b/docs/list.js index f199475f..0096404d 100644 --- a/docs/list.js +++ b/docs/list.js @@ -4,8 +4,7 @@ /** - * Instances of this class (herein referred to as “lists”) will be returned when accessing - * object properties whose type is `"list"` + * 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. diff --git a/docs/realm.js b/docs/realm.js index 0769ccb6..f42df6c0 100644 --- a/docs/realm.js +++ b/docs/realm.js @@ -3,7 +3,7 @@ */ /** - * A Realm instance (also referred to as a realm) represents a Realm database. + * A Realm instance represents a Realm database. * ```js * const Realm = require('realm'); * ``` diff --git a/docs/results.js b/docs/results.js index 8db20261..3ac760f4 100644 --- a/docs/results.js +++ b/docs/results.js @@ -4,8 +4,8 @@ /** - * Instances of this class (herein referred to as “results”) are typically **live** collections - * returned by {@link Realm#objects objects()} that will update as new objects are either + * 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 From a2dca06fe1b6081cbf6bdb7e46c3a58158f54eed Mon Sep 17 00:00:00 2001 From: Scott Kyle Date: Fri, 12 Feb 2016 02:47:08 -0800 Subject: [PATCH 3/3] Add simple test for generating API docs --- scripts/test.sh | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/test.sh b/scripts/test.sh index d25df2d9..c6dc2355 100755 --- a/scripts/test.sh +++ b/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 ;;