[ci skip] update schema method documentation (#5896)

* Fixed @param doc tag in model.js that was breaking docs build.

* Updating documentation for Model.schema() to include intended use case and how to set a default schema for a model.

lib/model.js

@@ -1031,11 +1031,20 @@ Model.prototype.dropSchema = function(schema) {
  * Apply a schema to this model. For postgres, this will actually place the schema in front of the table name - `"schema"."tableName"`,
  * Apply a schema to this model. For postgres, this will actually place the schema in front of the table name - `"schema"."tableName"`,
  * while the schema will be prepended to the table name for mysql and sqlite - `'schema.tablename'`.
  * while the schema will be prepended to the table name for mysql and sqlite - `'schema.tablename'`.
  *
  *
+ * This method is intended for use cases where the same model is needed in multiple schemas. In such a use case it is important
+ * to call `model.schema(schema, [options]).sync()` for each model to ensure the models are created in the correct schema.
+ *
+ * If a single default schema per model is needed, set the `options.schema='schema'` parameter during the `define()` call
+ * for the model.
+ *
  * @param {String} schema The name of the schema
  * @param {String} schema The name of the schema
  * @param {Object} [options]
  * @param {Object} [options]
  * @param {String} [options.schemaDelimiter='.'] The character(s) that separates the schema name from the table name
  * @param {String} [options.schemaDelimiter='.'] The character(s) that separates the schema name from the table name
  * @param {Function} [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Function} [options.logging=false] A function that gets executed while running the query to log the sql.
  * @param {Boolean}  [options.benchmark=false] Pass query execution time in milliseconds as second argument to logging function (options.logging).
  * @param {Boolean}  [options.benchmark=false] Pass query execution time in milliseconds as second argument to logging function (options.logging).
+ *
+ * @see {Sequelize#define} for more information about setting a default schema.
+ *
  * @return {this}
  * @return {this}
  */
  */
 Model.prototype.schema = function(schema, options) { // testhint options:none
 Model.prototype.schema = function(schema, options) { // testhint options:none
@@ -1318,7 +1327,7 @@ Model.prototype.all = function(options) {
  * @param  {Boolean}                   [options.benchmark=false] Pass query execution time in milliseconds as second argument to logging function (options.logging).
  * @param  {Boolean}                   [options.benchmark=false] Pass query execution time in milliseconds as second argument to logging function (options.logging).
  * @param  {Object}                    [options.having]
  * @param  {Object}                    [options.having]
  * @param  {String}                    [options.searchPath=DEFAULT] An optional parameter to specify the schema search_path (Postgres only)
  * @param  {String}                    [options.searchPath=DEFAULT] An optional parameter to specify the schema search_path (Postgres only)
- * @param  {Boolean|Error Instance}    [options.rejectOnEmpty=false] Throws an error when no records found
+ * @param  {Boolean|Error}    [options.rejectOnEmpty=false] Throws an error when no records found
  *
  *
  * @see    {Sequelize#query}
  * @see    {Sequelize#query}
  * @return {Promise<Array<Instance>>}
  * @return {Promise<Array<Instance>>}