How do you know the parameters Model.prototype.save() function takes on mongoose?

Question

So, I know that the save function’s callback will accept at least two parameters, error, and the saved document. But when I try to check that on the documentation, the only information I se regarding the callback is

[fn] «Function» optional callback

The question is, why is Mongoose ignoring the information about the callback’s argument?

I read somewhere else that there is even third argument it can take, " The number of rows affected". How am I supposed to know about that, or if it is even true if it is not listed on the official documentation?

The purpose of these questions is to understand how to search documentation and to understand what to expect when you do that. Thanks!

Answer 1

The mongoose documentation isn't the best for these details. Some things are implemented in the MongoDB Node Driver, and other things aren't documented for whatever reason. I'm guessing the reason the callback isn't explained here is because it's the same callback as used in many methods, and they didn't want the repetition bulking out the documentation.

For example, the findOneAndRemove documentation does give the callback arguments. But it's not clear that it's the same callback signature for all these methods.

Callback Signature

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

When documentation fails you, your next option is to read the source code. Mongoose is on github, and after some digging I found the save implementation in the model.js file.

Githubs search isn't great with code, unless the function you are searching for has a nice unique name. If you will be working with the library a lot, I recommend cloning the repo. Then use whatever text editor/IDE you are familiar with to search through it.

As the project is open source, I recommend that once you do decipher the documentation / code, you submit a pull request with an update for the documentation to make it clearer for the next person