docs(createIndex): better document createIndex(es) method and add examples

Adds documentation around the createIndex command that links
to docs.mongodb.com entry for an index definition. Also adds an
example showing multiple index definitions to createIndexes,
and adds some examples to createIndex. Makes explicit that
createIndexes uses different syntax from createIndex.

Fixes NODE-2024

Author: daprahamian

lib/collection.js

@@ -1119,7 +1119,7 @@ Collection.prototype.isCapped = function(options, callback) {
 /**
  * Creates an index on the db and collection collection.
  * @method
- * @param {(string|object)} fieldOrSpec Defines the index.
+ * @param {(string|array|object)} fieldOrSpec Defines the index.
  * @param {object} [options] Optional settings.
  * @param {(number|string)} [options.w] The write concern.
  * @param {number} [options.wtimeout] The write concern timeout.
@@ -1138,6 +1138,25 @@ Collection.prototype.isCapped = function(options, callback) {
  * @param {ClientSession} [options.session] optional session to use for this operation
  * @param {Collection~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
+ * @example
+ * const collection = client.db('foo').collection('bar');
+ *
+ * await collection.createIndex({ a: 1, b: -1 });
+ *
+ * // Alternate syntax for { c: 1, d: -1 } that ensures order of indexes
+ * await collection.createIndex([ [c, 1], [d, -1] ]);
+ *
+ * // Equivalent to { e: 1 }
+ * await collection.createIndex('e');
+ *
+ * // Equivalent to { f: 1, g: 1 }
+ * await collection.createIndex(['f', 'g'])
+ *
+ * // Equivalent to { h: 1, i: -1 }
+ * await collection.createIndex([ { h: 1 }, { i: -1 } ]);
+ *
+ * // Equivalent to { j: 1, k: -1, l: 2d }
+ * await collection.createIndex(['j', ['k', -1], { l: '2d' }])
  */
 Collection.prototype.createIndex = function(fieldOrSpec, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});
@@ -1153,16 +1172,43 @@ Collection.prototype.createIndex = function(fieldOrSpec, options, callback) {
   return executeOperation(this.s.topology, createIndexOperation, callback);
 };
 
+/**
+ * @typedef {object} Collection~IndexDefinition
+ * @description A definition for an index. Used by the createIndex command.
+ * @see https://docs.mongodb.com/manual/reference/command/createIndexes/
+ */
+
 /**
  * Creates multiple indexes in the collection, this method is only supported for
  * MongoDB 2.6 or higher. Earlier version of MongoDB will throw a command not supported
- * error. Index specifications are defined at http://docs.mongodb.org/manual/reference/command/createIndexes/.
+ * error.
+ *
+ * **Note**: Unlike {@link Collection#createIndex createIndex}, this function takes in raw index specifications.
+ * Index specifications are defined {@link http://docs.mongodb.org/manual/reference/command/createIndexes/ here}.
+ *
  * @method
- * @param {array} indexSpecs An array of index specifications to be created
+ * @param {Collection~IndexDefinition[]} indexSpecs An array of index specifications to be created
  * @param {Object} [options] Optional settings
  * @param {ClientSession} [options.session] optional session to use for this operation
  * @param {Collection~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
+ * @example
+ * const collection = client.db('foo').collection('bar');
+ * await collection.createIndexes([
+ *   // Simple index on field fizz
+ *   {
+ *     key: { fizz: 1 },
+ *   }
+ *   // wildcard index
+ *   {
+ *     key: { '$**': 1 }
+ *   },
+ *   // named index on darmok and jalad
+ *   {
+ *     key: { darmok: 1, jalad: -1 }
+ *     name: 'tanagra'
+ *   }
+ * ]);
  */
 Collection.prototype.createIndexes = function(indexSpecs, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});