Improve api docs (#920)

* Set docs title in configuration

* Add markdown plugin to jsdoc

* Add query language tutorial to docs

* jsdoc template submodule updated

* Add query docs

* Document placeholders and composition operators

* Add logo

* Add note about boolean checks

* Fixes as per PR comments

docs/collection.js

@@ -43,6 +43,8 @@ class Collection {
      *   (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.
+     * 
+     * See {@tutorial query-language} for details about the query language.
      * @example
      * let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
      */

docs/conf.json

@@ -14,9 +14,13 @@
   },
   "plugins": ["plugins/markdown"],
   "templates": {
+    "applicationName": "Realm JavaScript",
     "cleverLinks": true,
     "default": {
-      "outputSourceFiles": false
+      "outputSourceFiles": false,
+      "staticFiles": {
+        "paths": ["docs/static"]
+      }
     }
   }
 }

docs/jsdoc-template

@@ -1 +1 @@
-Subproject commit ab495962a2cf92718374d53f9b7c2f7b7d164068
+Subproject commit 4e014653f07066eb8652b1920a75969c5bc6e3f8

docs/plugins/markdown.js

@@ -0,0 +1,89 @@
+/**
+ * @overview Translate doclet descriptions from MarkDown into HTML.
+ * @module plugins/markdown
+ * @author Michael Mathews <micmath@gmail.com>
+ * @author Ben Blank <ben.blank@gmail.com>
+ */
+'use strict';
+
+var env = require('jsdoc/env');
+
+var config = env.conf.markdown || {};
+var defaultTags = [
+    'author',
+    'classdesc',
+    'description',
+    'exceptions',
+    'params',
+    'properties',
+    'returns',
+    'see'
+];
+var hasOwnProp = Object.prototype.hasOwnProperty;
+var parse = require('jsdoc/util/markdown').getParser();
+var tags = [];
+var excludeTags = [];
+
+function shouldProcessString(tagName, text) {
+    var shouldProcess = true;
+
+    // we only want to process `@author` and `@see` tags that contain Markdown links
+    if ( (tagName === 'author' || tagName === 'see') && text.indexOf('[') === -1 ) {
+        shouldProcess = false;
+    }
+
+    return shouldProcess;
+}
+
+/**
+ * Process the markdown source in a doclet. The properties that should be
+ * processed are configurable, but always include "classdesc", "description",
+ * "params", "properties", and "returns".  Handled properties can be bare
+ * strings, objects, or arrays of objects.
+ */
+function process(doclet) {
+    tags.forEach(function(tag) {
+        if ( !hasOwnProp.call(doclet, tag) ) {
+            return;
+        }
+
+        if (typeof doclet[tag] === 'string' && shouldProcessString(tag, doclet[tag]) ) {
+            doclet[tag] = parse(doclet[tag]);
+        }
+        else if ( Array.isArray(doclet[tag]) ) {
+            doclet[tag].forEach(function(value, index, original) {
+                var inner = {};
+                inner[tag] = value;
+                process(inner);
+                original[index] = inner[tag];
+            });
+        }
+        else if (doclet[tag]) {
+            process(doclet[tag]);
+        }
+    });
+}
+
+// set up the list of "tags" (properties) to process
+if (config.tags) {
+    tags = config.tags.slice();
+}
+// set up the list of default tags to exclude from processing
+if (config.excludeTags) {
+    excludeTags = config.excludeTags.slice();
+}
+defaultTags.forEach(function(tag) {
+    if (excludeTags.indexOf(tag) === -1 && tags.indexOf(tag) === -1) {
+        tags.push(tag);
+    }
+});
+
+exports.handlers = {
+    /**
+     * Translate markdown syntax in a new doclet's description into HTML. Is run
+     * by JSDoc 3 whenever a "newDoclet" event fires.
+     */
+    newDoclet: function(e) {
+        process(e.doclet);
+    }
+};

docs/tutorials/query-language.md

@@ -0,0 +1,58 @@
+The Realm JavaScript SDK supports querying based on a language inspired by [NSPredicate](https://realm.io/news/nspredicate-cheatsheet/). 
+
+The {@link Realm.Collection#filtered Collection.filtered()} method is used to query a Realm:
+
+```JS
+let contacts = realm.objects('Contact');
+let friendsPage2 = contacts.filtered('type == "friend" AND name BEGINSWITH "B"');
+```
+
+It's possible to filter by linked or child objects with a keypath.
+
+Example:
+```JS
+let johnsChildren = realm.Object('Contact').filtered('father.name == "John"');
+```
+
+Query strings can use numbered (`$0`, `$1`, ...) placeholders. The succeeding parameters contain the values.
+Named placeholders are **not** yet supported.
+
+Example:
+```JS
+let merlots = wines.filtered('variety == $0 && vintage <= $1', 'Merlot', maxYear);
+```
+
+
+### Relational operators
+You can use equality comparison on all property types: 
+`==` and `!=` 
+
+Furthermore, the following can be used on numerical types:
+`<`, `<=`, `>`, `>=`
+
+Example:
+```JS
+let oldContacts = realm.objects('Contact').filtered('age > 2');
+```
+
+Note that for boolean properties, you should test against the expected keyword.
+
+Example:
+```JS
+let women = realm.objects('Contact').filtered('isMale == false');
+```
+
+### String operators
+For string properties, prefix, suffix, and substring queries are supported by using the `BEGINSWITH`, `ENDSWITH`, and `CONTAINS` operators.
+
+For any string operation you can append `[c]` to the operator to make it case insensitive.
+
+Example:
+```JS
+let peopleWhoseNameContainsA = realm.objects('Contact').filtered('name CONTAINS[c] "a"');
+let Johns = realm.objects('Contact').filtered('name ==[c] "john"');
+```
+
+### Composition
+Use parentheses and the `&&`/`AND` and `||`/`OR` operators to compose queries. You can negate a predicate with `!`/`NOT`.
+

docs/tutorials/tutorials.json

@@ -0,0 +1,5 @@
+ {
+     "query-language": {
+         "title": "Query language"
+     }
+ }

package.json

@@ -48,7 +48,7 @@
     "set-version": "scripts/set-version.sh",
     "get-core-version": "scripts/download-core.sh --version",
     "get-sync-version": "scripts/download-core.sh --versionSync",
-    "jsdoc": "rm -rf docs/output && jsdoc -c docs/conf.json",
+    "jsdoc": "rm -rf docs/output && jsdoc -u docs/tutorials -p package.json -c docs/conf.json",
     "lint": "eslint",
     "test": "scripts/test.sh",
     "install": "node-pre-gyp install --fallback-to-build",