title: How does Mongoose's save callback work?
body: <p>For the MEAN stack, I'm learning about Mongoose's save() function, which takes a callback. Its <a href="http://mongoosejs.com/docs/api.html#model_Model-save" rel="noreferrer">API states</a>:</p>
  
  <pre><code>Model#save([options], [fn])
  
  Saves this document.
  
  Parameters:
  
  [options] &lt;Object&gt; options set `options.safe` to override [schema's safe option](http://mongoosejs.com//docs/guide.html#safe)
  [fn] &lt;Function&gt; optional callback
  </code></pre>
  
  <p>How do I know what arguments are in the optional callback? The API merely gives an example:</p>
  
  <pre><code>product.sold = Date.now();
  product.save(function (err, product, numAffected) {
    if (err) ..
  })
  The callback will receive three parameters
  
  err if an error occurred
  product which is the saved product
  numAffected will be 1 when the document was successfully persisted to MongoDB, otherwise 0.
  </code></pre>
  
  <hr>
  
  <p><strong>What I think the API should say about the optional callback is the following:</strong></p>
  
  <pre><code>[fn] &lt;Function&gt; optional callback with this structure:
  
       function(err, theDocumentToBeSaved, [isSaveSuccessful])
  </code></pre>
  
  <p>and it can be used like the following. <strong>Note that the second argument, the document, must be the same document that is calling the save.</strong> (Let me know if it's not the case.)</p>
  
  <pre><code>documentFoo.save(function(err, documentFoo, [isSaveSuccessful]){
      if(err){ return next(err); }
  
      if (isSaveSuccessful === 1){
  
          // documentFoo has been saved correctly 
          // do stuff with the saved documentFoo
      }
  }
  </code></pre>
  
  <p><strong>If my interpretation is correct, is that how the save callback parameters should always be structured?</strong></p>