Merge pull request Automattic#15113 from Automattic/vkarpov15/Automatticgh-15107

docs(connection+document+model): remove remaining references to remove(), clarify that deleteOne() does not execute until then() or exec()

Author: vkarpov15

lib/connection.js

@@ -663,7 +663,7 @@ Connection.prototype.withSession = async function withSession(executor) {
  *
  *     const session = await conn.startSession();
  *     let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
- *     await doc.remove();
+ *     await doc.deleteOne();
  *     // `doc` will always be null, even if reading from a replica set
  *     // secondary. Without causal consistency, it is possible to
  *     // get a doc back from the below query if the query reads from a

lib/document.js

@@ -2357,17 +2357,17 @@ Document.prototype.$isDefault = function(path) {
 };
 
 /**
- * Getter/setter, determines whether the document was removed or not.
+ * Getter/setter, determines whether the document was deleted. The `Model.prototype.deleteOne()` method sets `$isDeleted` if the delete operation succeeded.
  *
  * #### Example:
  *
- *     const product = await product.remove();
+ *     const product = await product.deleteOne();
  *     product.$isDeleted(); // true
- *     product.remove(); // no-op, doesn't send anything to the db
+ *     product.deleteOne(); // no-op, doesn't send anything to the db
  *
  *     product.$isDeleted(false);
  *     product.$isDeleted(); // false
- *     product.remove(); // will execute a remove against the db
+ *     product.deleteOne(); // will execute a remove against the db
  *
  *
  * @param {Boolean} [val] optional, overrides whether mongoose thinks the doc is deleted

lib/model.js

@@ -694,13 +694,20 @@ Model.prototype.$__where = function _where(where) {
 };
 
 /**
- * Delete this document from the db.
+ * Delete this document from the db. Returns a Query instance containing a `deleteOne` operation by this document's `_id`.
  *
  * #### Example:
  *
  *     await product.deleteOne();
  *     await Product.findById(product._id); // null
  *
+ * Since `deleteOne()` returns a Query, the `deleteOne()` will **not** execute unless you use either `await`, `.then()`, `.catch()`, or [`.exec()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.exec())
+ *
+ * #### Example:
+ *
+ *     product.deleteOne(); // Doesn't do anything
+ *     product.deleteOne().exec(); // Deletes the document, returns a promise
+ *
  * @return {Query} Query
  * @api public
  */
@@ -1879,8 +1886,6 @@ Model.translateAliases = function translateAliases(fields, errorOnDuplicates) {
 /**
  * Deletes the first document that matches `conditions` from the collection.
  * It returns an object with the property `deletedCount` indicating how many documents were deleted.
- * Behaves like `remove()`, but deletes at most one document regardless of the
- * `single` option.
  *
  * #### Example:
  *
@@ -1914,8 +1919,6 @@ Model.deleteOne = function deleteOne(conditions, options) {
 /**
  * Deletes all of the documents that match `conditions` from the collection.
  * It returns an object with the property `deletedCount` containing the number of documents deleted.
- * Behaves like `remove()`, but deletes all documents that match `conditions`
- * regardless of the `single` option.
  *
  * #### Example:
  *
@@ -2729,7 +2732,7 @@ Model.create = async function create(doc, options) {
  *     //   operationType: 'delete',
  *     //   ns: { db: 'mydb', coll: 'Person' },
  *     //   documentKey: { _id: 5a51b125c5500f5aa094c7bd } }
- *     await doc.remove();
+ *     await doc.deleteOne();
  *
  * @param {Array} [pipeline]
  * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#watch)
@@ -2777,7 +2780,7 @@ Model.watch = function(pipeline, options) {
  *
  *     const session = await Person.startSession();
  *     let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
- *     await doc.remove();
+ *     await doc.deleteOne();
  *     // `doc` will always be null, even if reading from a replica set
  *     // secondary. Without causal consistency, it is possible to
  *     // get a doc back from the below query if the query reads from a