docs(document): add more info on $isNew

Fix #11990

lib/document.js

@@ -300,7 +300,35 @@ Object.defineProperty(Document.prototype, '$locals', {
 
 
 /**
- * Boolean flag specifying if the document is new.
+ * Boolean flag specifying if the document is new. If you create a document
+ * using `new`, this document will be considered "new". `$isNew` is how
+ * Mongoose determines whether `save()` should use `insertOne()` to create
+ * a new document or `updateOne()` to update an existing document.
+ *
+ * #### Example:
+ *     const user = new User({ name: 'John Smith' });
+ *     user.$isNew; // true
+ * 
+ *     await user.save(); // Sends an `insertOne` to MongoDB
+ *
+ * On the other hand, if you load an existing document from the database
+ * using `findOne()` or another [query operation](/docs/queries.html),
+ * `$isNew` will be false.
+ *
+ * #### Example:
+ *     const user = await User.findOne({ name: 'John Smith' });
+ *     user.$isNew; // false
+ *
+ * For subdocuments, `$isNew` is true if either the parent has `$isNew` set,
+ * or if you create a new subdocument.
+ *
+ * #### Example:
+ *     // Assume `Group` has a document array `users`
+ *     const group = await Group.findOne();
+ *     group.users[0].$isNew; // false
+ *
+ *     group.users.push({ name: 'John Smith' });
+ *     group.users[1].$isNew; // true
  *
  * @api public
  * @property $isNew
@@ -311,7 +339,7 @@ Object.defineProperty(Document.prototype, '$locals', {
 Document.prototype.$isNew;
 
 /**
- * Boolean flag specifying if the document is new.
+ * Legacy alias for `$isNew`.
  *
  * @api public
  * @property isNew