joyent/node-triton#155 doc TritonApi method callback guidelines

lib/tritonapi.js

@@ -22,6 +22,7 @@
  * - support for waiting for async operations to complete via "wait" parameters;
  * - profile handling.
  *
+ *
  * Preparing a TritonApi is a three-step process. (Note: Some users might
  * prefer to use the `createClient` convenience function in "index.js" that
  * wraps up all three steps into a single call.)
@@ -38,7 +39,8 @@
  *              at new SigningError (/Users/trentm/tmp/node-triton/lib/errors.js:173:23)
  *              at CloudApi._getAuthHeaders (/Users/trentm/tmp/node-triton/lib/cloudapi2.js:185:22)
  *
- * Usage:
+ * # Usage
+ *
  *      var mod_triton = require('triton');
  *
  *      // 1. Create the TritonApi instance.
@@ -78,6 +80,31 @@
  *              });
  *          });
  *      });
+ *
+ *
+ * # TritonApi method callback patterns
+ *
+ * Guidelines for the `cb` callback form for TritonApi methods are as follows:
+ *
+ * - Methods that delete a resource (i.e. call DELETE endpoints on cloudapi)
+ *   should have a callback of one of the following forms:
+ *          function (err)
+ *          function (err, res)             # if 'res' is useful to caller
+ *   where `res` is the response object. The latter form is used if there
+ *   is a reasonable use case for a caller needing it.
+ *
+ * - Other methods should have a callback of one of the following forms:
+ *          function (err, theThing)
+ *          function (err, theThing, res)
+ *          function (err, _, res)          # no meaningful body; useful 'res'
+ *          function (err)
+ *   `res` is the response object (from the original cloudapi request, in
+ *   the case of methods that make an async request, and then poll waiting
+ *   for completion). `theThing` is an endpoint-specific object. Typically it
+ *   is the parsed JSON body from the cloudapi response. In some cases there
+ *   is no meaningful response body (e.g. for RenameMachine), but the res can
+ *   be useful. Here we use `_` to put a placeholder for the body, and keep
+ *   `res` in the third position.
  */
 /* END JSSTYLED */