docs(document): clarify that transform function option applies to s…

…ubdocs

Fix #13757

lib/document.js

@@ -3901,14 +3901,24 @@ Document.prototype.$toObject = function(options, json) {
  *
  * _Note: if a transform function returns `undefined`, the return value will be ignored._
  *
- * Transformations may also be applied inline, overridding any transform set in the options:
+ * Transformations may also be applied inline, overridding any transform set in the schema options.
+ * Any transform function specified in `toObject` options also propagates to any subdocuments.
  *
- *     function xform (doc, ret, options) {
- *       return { inline: ret.name, custom: true }
+ *     function deleteId(doc, ret, options) {
+ *       delete ret._id;
+ *       return ret;
  *     }
  *
- *     // pass the transform as an inline option
- *     doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }
+ *     const schema = mongoose.Schema({ name: String, docArr: [{ name: String }] });
+ *     const TestModel = mongoose.model('Test', schema);
+ *
+ *     const doc = new TestModel({ name: 'test', docArr: [{ name: 'test' }] });
+ *
+ *     // pass the transform as an inline option. Deletes `_id` property
+ *     // from both the top-level document and the subdocument.
+ *     const obj = doc.toObject({ transform: deleteId });
+ *     obj._id; // undefined
+ *     obj.docArr[0]._id; // undefined
  *
  * If you want to skip transformations, use `transform: false`:
  *