diff --git a/docs/collection.js b/docs/collection.js
index 5cb8852e..0db883aa 100644
--- a/docs/collection.js
+++ b/docs/collection.js
@@ -18,17 +18,39 @@
 
 /**
  * Abstract base class containing methods shared by {@link Realm.List} and {@link Realm.Results}.
+ *
+ * A Realm Collection is a homogenous sequence of values of any of the types
+ * that can be stored as properties of Realm objects. A collection can be
+ * accessed in any of the ways that a normal Javascript Array can, including
+ * subscripting, enumerating with `for-of` and so on.
+ *
  * @memberof Realm
  * @since 0.11.0
  */
 class Collection {
     /**
-     * The number of objects in the collection.
+     * The number of values in the collection.
      * @type {number}
      * @readonly
      */
     get length() {}
 
+    /**
+     * The {@linkplain Realm~PropertyType type} of values in the collection.
+     * @type {string}
+     * @readonly
+     * @since 2.0.0
+     */
+    get type() {}
+
+    /**
+     * Whether `null` is a valid value for the collection.
+     * @type {boolean}
+     * @readonly
+     * @since 2.0.0
+     */
+    get optional() {}
+
     /**
      * Checks if this collection has not been deleted and is part of a valid Realm.
      * @returns {boolean} indicating if the collection can be safely accessed.
@@ -38,12 +60,15 @@ class Collection {
 
     /**
      * Returns new _Results_ that represent this collection being filtered by the provided query.
+     *
      * @param {string} query - Query used to filter objects from the collection.
      * @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.
-     * 
+     * @returns {Realm.Results<T>} filtered according to the provided query.
+     *
+     * This is currently only supported for collections of Realm Objects.
+     *
      * See {@tutorial query-language} for details about the query language.
      * @example
      * let merlots = wines.filtered('variety == "Merlot" && vintage <= $0', maxYear);
@@ -51,43 +76,76 @@ class Collection {
     filtered(query, ...arg) {}
 
     /**
-     * Returns new _Results_ that represent this collection being sorted by the provided property
-     * (or properties) of each object.
-     * @param {string|Realm.Results~SortDescriptor[]} descriptor - The property name(s) to sort
-     *   the objects in the collection.
-     * @param {boolean} [reverse=false] - May only be provided if `descriptor` is a string.
+     * Returns new _Results_ that represent a sorted view of this collection.
+     *
+     * A collection of Realm Objects can be sorted on one or more properties of
+     * those objects, or of properties of objects linked to by those objects.
+     * To sort by a single property, simply pass the name of that property to
+     * `sorted()`, optionally followed by a boolean indicating if the sort should be reversed.
+     * For more than one property, you must pass an array of
+     * {@linkplain Realm.Collection~SortDescriptor sort descriptors} which list
+     * which properties to sort on.
+     *
+     * Collections of other types sort on the values themselves rather than
+     * properties of the values, and so no property name or sort descriptors
+     * should be supplied.
+     *
+     * @example
+     * // Sort wines by age
+     * wines.sorted('age')
+     * @example
+     * // Sort wines by price in descending order, then sort ties by age in
+     * // ascending order
+     * wines.sorted([['price', false], ['age'])
+     * @example
+     * // Sort a list of numbers in ascending order
+     * let sortedPrices = wine.pricesSeen.sort()
+     * @example
+     * // Sort people by how expensive their favorite wine is
+     * people.sort("favoriteWine.price")
+     *
+     * @param {string|Realm.Collection~SortDescriptor[]} [descriptor] - The property name(s) to sort the collection on.
+     * @param {boolean} [reverse=false] - Sort in descending order rather than ascended.
+     *   May not be supplied if `descriptor` is an array of sort descriptors.
      * @throws {Error} If a specified property does not exist.
-     * @returns {Realm.Results} sorted according to the arguments passed in
+     * @returns {Realm.Results<T>} sorted according to the arguments passed in.
      */
     sorted(descriptor, reverse) {}
 
     /**
-     * Create a frozen snapshot of the collection. This means objects added to and removed from the
-     * original collection will not be reflected in the _Results_ returned by this method.
-     * However, objects deleted from the Realm will become `null` at their respective indices.
-     * This is **not** a _deep_ snapshot, meaning the objects contained in this snapshot will
-     * continue to update as changes are made to them.
-     * @returns {Realm.Results} which will **not** live update.
+     * Create a frozen snapshot of the collection.
+     *
+     * Values added to and removed from the original collection will not be
+     * reflected in the _Results_ returned by this method, including if the
+     * values of properties are changed to make them match or not match any
+     * filters applied.
+     *
+     * This is **not** a _deep_ snapshot. Realm objects contained in this
+     * snapshot will continue to update as changes are made to them, and if
+     * they are deleted from the Realm they will be replaced by `null` at the
+     * respective indices.
+     *
+     * @returns {Realm.Results<T>} which will **not** live update.
      */
     snapshot() {}
 
     /**
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
-     * @returns {Realm.Collection~Iterator} of each `[index, object]` pair in the collection
+     * @returns {Realm.Collection~Iterator<T>} of each `[index, object]` pair in the collection
      * @since 0.11.0
      */
     entries() {}
 
     /**
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
-     * @returns {Realm.Collection~Iterator} of each index in the collection
+     * @returns {Realm.Collection~Iterator<T>} of each index in the collection
      * @since 0.11.0
      */
     keys() {}
 
     /**
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values Array.prototype.values}
-     * @returns {Realm.Collection~Iterator} of each Realm object in the collection
+     * @returns {Realm.Collection~Iterator<T>} of each Realm object in the collection
      * @since 0.11.0
      */
     values() {}
@@ -101,7 +159,7 @@ class Collection {
      * spread operators, and more.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator Symbol.iterator}
      *   and the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable iterable protocol}
-     * @returns {Realm.Collection~Iterator} of each Realm object in the collection
+     * @returns {Realm.Collection~Iterator<T>} of each Realm object in the collection
      * @since 0.11.0
      * @example
      * for (let object of collection) {
@@ -128,7 +186,7 @@ class Collection {
      *   index will be include in the return value. If negative, then the end index will be
      *   counted from the end of the collection. If omitted, then all objects from the start
      *   index will be included in the return value.
-     * @returns {Realm.Object[]} containing the objects from the start index up to, but not
+     * @returns {T[]} containing the objects from the start index up to, but not
      *   including, the end index.
      * @since 0.11.0
      */
@@ -143,7 +201,7 @@ class Collection {
      *   - `index` – The index of the object being processed in the collection.
      *   - `collection` – The collection itself.
      * @param {object} [thisArg] - The value of `this` when `callback` is called.
-     * @returns {Realm.Object|undefined} if the `callback` did not return `true` for any object
+     * @returns {T|undefined} if the `callback` did not return `true` for any object
      *   in the collection.
      * @since 0.11.0
      */
@@ -166,10 +224,11 @@ class Collection {
 
    /**
     Finds the index of the given object in the collection.
-    * @param {Realm.Object} [object] - The object to search for in the collection.
-    * @throws {Error} If the argument does not belong to the realm.
-    * @returns {number} representing the index where the object was found, or `-1`
-    *   if not in collection.
+    * @param {T} object - The value to search for in the collection.
+    * @throws {Error} If the argument is a {@link Realm.Object} that does not
+    *                 belong to the same Realm as the collection.
+    * @returns {number} representing the index where the value was found, or
+    *          `-1` if not in collection.
     * @since 1.8.2
     */
    indexOf(object) {}
@@ -294,7 +353,7 @@ class Collection {
     /**
      * Remove the listener `callback` from the collection instance.
      * @param {function(collection, changes)} callback - Callback function that was previously
- *       added as a listener through the {@link Collection#addListener addListener} method.
+     *   added as a listener through the {@link Collection#addListener addListener} method.
      * @throws {Error} If `callback` is not a function.
      */
     removeListener(callback) {}
@@ -324,8 +383,9 @@ class Collection {
  */
 
 /**
- * The sort descriptors may either just be a string representing the property name, **or** an
- * array with two items: `[propertyName, reverse]`
+ * A sort descriptor is either a string containing one or more property names
+ * separate by dots, **or** an array with two items: `[propertyName, reverse]`.
+ *
  * @typedef Realm.Collection~SortDescriptor
  * @type {string|Array}
  */
diff --git a/docs/list.js b/docs/list.js
index 66e14d06..500e4e4c 100644
--- a/docs/list.js
+++ b/docs/list.js
@@ -19,59 +19,70 @@
 /**
  * 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.
+ *
+ * Lists mostly behave like normal Javascript Arrays, except for that they can
+ * only store values of a single type (indicated by the `type` and `optional`
+ * properties of the List), and can only be modified inside a {@linkplain
+ * Realm#write write} transaction.
+ *
  * @extends Realm.Collection
  * @memberof Realm
  */
 class List extends Collection {
     /**
-     * Remove the **last** object from the list and return it.
+     * Remove the **last** value from the list and return it.
      * @throws {Error} If not inside a write transaction.
-     * @returns {Realm.Object|undefined} if the list is empty.
+     * @returns {T|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.
+     * Add one or more values to the _end_ of the list.
+     *
+     * @param {...T} value - Values to add to the list.
+     * @throws {TypeError} If a `value` is not of a type which can be stored in
+     *   the list, or if an object being added to the list does not match the
+     *   {@linkcode Realm~ObjectSchema object schema} for the list.
+     *
      * @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.
+     * @returns {number} equal to the new {@link Realm.List#length length} of
+     *          the list after adding the values.
      */
-    push(...object) {}
+    push(...value) {}
 
     /**
-     * Remove the **first** object from the list and return it.
+     * Remove the **first** value from the list and return it.
      * @throws {Error} If not inside a write transaction.
-     * @returns {Realm.Object|undefined} if the list is empty.
+     * @returns {T|undefined} if the list is empty.
      */
     shift() {}
 
     /**
-     * Changes the contents of the list by removing objects and/or inserting new objects.
+     * Changes the contents of the list by removing value and/or inserting new value.
+     *
      * @see {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice Array.prototype.splice}
      * @param {number} index - The start index. If greater than the length of the list,
      *   the start index will be set to the length instead. If negative, then the start index
      *   will be counted from the end of the list (e.g. `list.length - index`).
-     * @param {number} [count] - The number of objects to remove from the list. If not provided,
-     *   then all objects from the start index through the end of the list will be removed.
-     * @param {...Realm.Object} [object] - Objects to insert into the list starting at `index`.
-     * @returns {Realm.Object[]} containing the objects that were removed from the list. The
-     *   array is empty if no objects were removed.
+     * @param {number} [count] - The number of values to remove from the list.
+     *   If not provided, then all values from the start index through the end of
+     *   the list will be removed.
+     * @param {...T} [value] - Values to insert into the list starting at `index`.
+     * @returns {T[]} containing the value that were removed from the list. The
+     *   array is empty if no value were removed.
      */
     splice(index, count, ...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.
+     * Add one or more values to the _beginning_ of the list.
+     *
+     * @param {...T} value - Values to add to the list.
+     * @throws {TypeError} If a `value` is not of a type which can be stored in
+     *   the list, or if an object being added to the list does not match the
+     *   {@linkcode Realm~ObjectSchema object schema} for the list.
      * @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.
+     * @returns {number} equal to the new {@link Realm.List#length length} of
+     *          the list after adding the values.
      */
     unshift(...object) {}
-}
\ No newline at end of file
+}
diff --git a/docs/realm.js b/docs/realm.js
index e379d1c7..8a3aa209 100644
--- a/docs/realm.js
+++ b/docs/realm.js
@@ -95,7 +95,7 @@ class Realm {
      * Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully
      * synchronized before it is available.
      * @param {Realm~Configuration} config
-     * @returns {ProgressPromise} - a promise that will be resolved with the realm instance when it's available.
+     * @returns {ProgressPromise} - a promise that will be resolved with the Realm instance when it's available.
      */
     static open(config) {}
 
@@ -103,7 +103,7 @@ class Realm {
      * Open a Realm asynchronously with a callback. If the Realm is synced, it will be fully
      * synchronized before it is available.
      * @param {Realm~Configuration} config
-     * @param  {callback(error, realm)} - will be called when the realm is ready.
+     * @param  {callback(error, realm)} - will be called when the Realm is ready.
      * @param  {callback(transferred, transferable)} [progressCallback] - an optional callback for download progress notifications
      * @throws {Error} If anything in the provided `config` is invalid.
      */
@@ -286,6 +286,7 @@ Realm.defaultPath;
  * @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`.
+ *   If omitted, the schema will be read from the existing Realm file.
  * @property {number} [schemaVersion] - **Required** (and must be incremented) after
  *   changing the `schema`.
  * @property {Object} [sync] - Sync configuration parameters with the following
@@ -350,19 +351,39 @@ Realm.defaultPath;
  *   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.
+ *
+ * @example
+ * let MyClassSchema = {
+ *     name: 'MyClass',
+ *     primaryKey: 'pk',
+ *     properties: {
+ *         pk: 'int',
+ *         optionalFloatValue: 'float?' // or {type: 'float', optional: true}
+ *         listOfStrings: 'string[]',
+ *         listOfOptionalDates: 'date?[]',
+ *         indexedInt: {type: 'int', indexed: true}
+ *
+ *         linkToObject: 'MyClass',
+ *         listOfObjects: 'MyClass[]', // or {type: 'list', objectType: 'MyClass'}
+ *         objectsLinkingToThisObject: {type: 'linkingObjects', objectType: 'MyClass', property: 'linkToObject'}
+ *     }
+ * };
  */
 
 /**
  * @typedef Realm~ObjectSchemaProperty
  * @type {Object}
  * @property {Realm~PropertyType} type - The type of this property.
- * @property {string} [objectType] - **Required**  when `type` is `"list"` or `"linkingObjects"`,
- *   and must match the type of an object in the same schema.
+ * @property {Realm~PropertyType} [objectType] - **Required**  when `type` is `"list"` or `"linkingObjects"`,
+ *   and must match the type of an object in the same schema, or, for `"list"`
+ *   only, any other type which may be stored as a Realm property.
  * @property {string} [property] - **Required** when `type` is `"linkingObjects"`, and must match
  *   the name of a property on the type specified in `objectType` that links to the type this property belongs to.
  * @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`.
+ *   For `"list"` properties of non-object types, this instead signals whether the values inside the list may be assigned `null` or `undefined`.
+ *   This is not supported for `"list"` properties of object types and `"linkingObjects"` properties.
  * @property {boolean} [indexed] - Signals if this property should be indexed. Only supported for
  *   `"string"`, `"int"`, and `"bool"` properties.
  */
@@ -376,10 +397,21 @@ Realm.defaultPath;
  */
 
 /**
- * A property type may be specified as one of the standard builtin types, or as an object type
- * inside the same schema.
+ * A property type may be specified as one of the standard builtin types, or as
+ * an object type inside the same schema.
+ *
+ * When specifying property types in an {@linkplain Realm~ObjectSchema object schema}, you
+ * may append `?` to any of the property types to indicate that it is optional
+ * (i.e. it can be `null` in addition to the normal values) and `[]` to
+ * indicate that it is instead a list of that type. For example,
+ * `optionalIntList: 'int?[]'` would declare a property which is a list of
+ * nullable integers. The property types reported by {@linkplain Realm.Collection
+ * collections} and in a Realm's schema will never
+ * use these forms.
+ *
  * @typedef Realm~PropertyType
  * @type {("bool"|"int"|"float"|"double"|"string"|"date"|"data"|"list"|"linkingObjects"|"<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.
diff --git a/docs/results.js b/docs/results.js
index d04818e6..2a406a33 100644
--- a/docs/results.js
+++ b/docs/results.js
@@ -23,6 +23,7 @@
  * {@link Realm.Results#snapshot snapshot()}, however, will **not** live update
  * (and listener callbacks added through {@link Realm.Results#addListener addListener()}
  * will thus never be called).
+ *
  * @extends Realm.Collection
  * @memberof Realm
  */