docs: clarify that transforms defined in toObject() options are applied to subdocs

Fix #8260

Author: vkarpov15

lib/document.js

@@ -2970,7 +2970,6 @@ Document.prototype.$toObject = function(options, json) {
  *
  * If you want to skip transformations, use `transform: false`:
  *
- *     if (!schema.options.toObject) schema.options.toObject = {};
  *     schema.options.toObject.hide = '_id';
  *     schema.options.toObject.transform = function (doc, ret, options) {
  *       if (options.hide) {
@@ -2986,7 +2985,26 @@ Document.prototype.$toObject = function(options, json) {
  *     doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
  *     doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }
  *
- * Transforms are applied _only to the document and are not applied to sub-documents_.
+ * If you pass a transform in `toObject()` options, Mongoose will apply the transform
+ * to [subdocuments](/docs/subdocs.html) in addition to the top-level document.
+ * Similarly, `transform: false` skips transforms for all subdocuments.
+ * Note that this is behavior is different for transforms defined in the schema:
+ * if you define a transform in `schema.options.toObject.transform`, that transform
+ * will **not** apply to subdocuments.
+ *
+ *     const memberSchema = new Schema({ name: String, email: String });
+ *     const groupSchema = new Schema({ members: [memberSchema], name: String, email });
+ *     const Group = mongoose.model('Group', groupSchema);
+ *
+ *     const doc = new Group({
+ *       name: 'Engineering',
+ *       email: 'dev@mongoosejs.io',
+ *       members: [{ name: 'Val', email: 'val@mongoosejs.io' }]
+ *     });
+ *
+ *     // Removes `email` from both top-level document **and** array elements
+ *     // { name: 'Engineering', members: [{ name: 'Val' }] }
+ *     doc.toObject({ transform: (doc, ret) => { delete ret.email; return ret; } });
  *
  * Transforms, like all of these options, are also available for `toJSON`. See [this guide to `JSON.stringify()`](https://thecodebarbarian.com/the-80-20-guide-to-json-stringify-in-javascript.html) to learn why `toJSON()` and `toObject()` are separate functions.
  *