docs(schema): clarify that uppercase, lowercase, and trim optio…

…ns for SchemaString don't affect RegExp queries

Fix #8333

lib/schema/string.js

@@ -232,6 +232,14 @@ SchemaString.prototype.enum = function() {
  *     console.log(m.email) // someemail@example.com
  *     M.find({ email: 'SomeEmail@example.com' }); // Queries by 'someemail@example.com'
  *
+ * Note that `lowercase` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Still queries for documents whose `email` matches the regular
+ *     // expression /SomeEmail/. Mongoose does **not** convert the RegExp
+ *     // to lowercase.
+ *     M.find({ email: /SomeEmail/ });
+ *
  * @api public
  * @return {SchemaType} this
  */
@@ -262,6 +270,12 @@ SchemaString.prototype.lowercase = function(shouldApply) {
  *     console.log(m.caps) // AN EXAMPLE
  *     M.find({ caps: 'an example' }) // Matches documents where caps = 'AN EXAMPLE'
  *
+ * Note that `uppercase` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Mongoose does **not** convert the RegExp to uppercase.
+ *     M.find({ email: /an example/ });
+ *
  * @api public
  * @return {SchemaType} this
  */
@@ -288,12 +302,21 @@ SchemaString.prototype.uppercase = function(shouldApply) {
  *
  * ####Example:
  *
- *     var s = new Schema({ name: { type: String, trim: true }})
- *     var M = db.model('M', s)
- *     var string = ' some name '
- *     console.log(string.length) // 11
- *     var m = new M({ name: string })
- *     console.log(m.name.length) // 9
+ *     var s = new Schema({ name: { type: String, trim: true }});
+ *     var M = db.model('M', s);
+ *     var string = ' some name ';
+ *     console.log(string.length); // 11
+ *     var m = new M({ name: string });
+ *     console.log(m.name.length); // 9
+ *
+ *     // Equivalent to `findOne({ name: string.trim() })`
+ *     M.findOne({ name: string });
+ *
+ * Note that `trim` does **not** affect regular expression queries:
+ *
+ * ####Example:
+ *     // Mongoose does **not** trim whitespace from the RegExp.
+ *     M.find({ name: / some name / });
  *
  * @api public
  * @return {SchemaType} this