From c1e5cb03cfa4f9fe6eca6b94402f73498c04c06d Mon Sep 17 00:00:00 2001
From: Scott Kyle <scott@appden.com>
Date: Fri, 19 Feb 2016 01:44:52 -0800
Subject: [PATCH] Update API docs with sorted/filtered changes

---
 docs/jsdoc-template |  2 +-
 docs/list.js        | 24 +++++++++++++++++++++
 docs/realm.js       | 13 +++---------
 docs/results.js     | 52 ++++++++++++++++++++++++++++++++-------------
 4 files changed, 65 insertions(+), 26 deletions(-)

diff --git a/docs/jsdoc-template b/docs/jsdoc-template
index f21b8a34..95172345 160000
--- a/docs/jsdoc-template
+++ b/docs/jsdoc-template
@@ -1 +1 @@
-Subproject commit f21b8a34130c287429ba1e8f120e3645b45766c8
+Subproject commit 951723451f8ff082d657135486b6fb30de8c2a26
diff --git a/docs/list.js b/docs/list.js
index 0096404d..b7ed3df9 100644
--- a/docs/list.js
+++ b/docs/list.js
@@ -18,6 +18,30 @@ class List {
      */
     get length() {}
 
+    /**
+     * Returns new results that represent this list being filtered by the provided query.
+     * ```js
+     * let merlots = wines.filtered('varietal == "Merlot" && vintage <= $0', maxYear);
+     * ```
+     * @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 the query or any other argument passed into this method is invalid.
+     * @returns {Realm.Results} filtered according to the provided query.
+     */
+    filtered(query, ...arg) {}
+
+    /**
+     * Returns new results that represent this list being sorted by the provided property
+     *   (or properties) of each object.
+     * @param {string|Realm.Results~SortDescriptor[]} descriptor - The property name(s) to sort
+     *   results by.
+     * @param {boolean} [reverse=false] - May only be provided if `descriptor` is a string.
+     * @throws {Error} If a specified property does not exist.
+     * @returns {Realm.Results} sorted according to the arguments passed in
+     */
+    sorted(descriptor, reverse) {}
+
     /**
      * 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
diff --git a/docs/realm.js b/docs/realm.js
index f42df6c0..d1b03905 100644
--- a/docs/realm.js
+++ b/docs/realm.js
@@ -46,18 +46,11 @@ class 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);
-     * ```
+     * Returns all objects of the given `type` in the Realm.
      * @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}
+     * @throws {Error} If type passed into this method is invalid.
+     * @returns {Realm.Results} that will live-update as objects are created and destroyed.
      */
     objects(type, query, ...arg) {}
 
diff --git a/docs/results.js b/docs/results.js
index 3ac760f4..5537e47b 100644
--- a/docs/results.js
+++ b/docs/results.js
@@ -11,26 +11,48 @@
  * @memberof Realm
  */
 class Results {
-   /**
-    * The number of objects in the results.
-    * @type {number}
-    * @readonly
-    */
-   get length() {}
+    /**
+     * 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
+     * Returns new results that are filtered by the provided query.
+     * ```js
+     * let merlots = wines.filtered('varietal == "Merlot" && vintage <= $0', maxYear);
+     * ```
+     * @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 the query or any other argument passed into this method is invalid.
+     * @returns {Realm.Results} filtered according to the provided query.
+     */
+    filtered(query, ...arg) {}
+
+    /**
+     * Returns new results that are sorted by the provided property (or properties) of each object.
+     * @param {string|Realm.Results~SortDescriptor[]} descriptor - The property name(s) to sort
+     *   results by.
+     * @param {boolean} [reverse=false] - May only be provided if `descriptor` is a string.
+     * @throws {Error} If a specified property does not exist.
+     * @returns {Realm.Results} sorted according to the arguments passed in
+     */
+    sorted(descriptor, reverse) {}
+
+    /**
+     * Create a frozen snapshot of the results. 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) {}
 }
+
+/**
+ * The sort descriptors may either just be a string representing the property name, **or** an
+ * array with two items: `[propertyName, reverse]`
+ * @typedef Realm.Results~SortDescriptor
+ * @type {string|Array}
+ */