jsdoc comments

.eslintrc

@@ -30,6 +30,12 @@
         "no-sparse-arrays": [ 2 ],
         "no-unreachable": [ 2 ],
         "use-isnan": [ 2 ],
+        "valid-jsdoc": [ 2, {
+            "requireReturnDescription": false,
+            "prefer": {
+                "return": "returns"
+            }
+        }],
         "valid-typeof": [ 2 ],
 
         // best practices

lib/bunyan_helper.js

@@ -20,6 +20,14 @@ var STR_FMT = '[object %s<level=%d, limit=%d, maxRequestIds=%d>]';
 
 ///--- Helpers
 
+/**
+ * appends streams
+ * @private
+ * @function appendStream
+ * @param    {Stream}    streams the stream to append to
+ * @param    {Stream}    s       the stream to append
+ * @returns  {undefined}
+ */
 function appendStream(streams, s) {
     assert.arrayOfObject(streams, 'streams');
     assert.object(s, 'stream');
@@ -43,8 +51,9 @@ function appendStream(streams, s) {
  * A Bunyan stream to capture records in a ring buffer and only pass through
  * on a higher-level record. E.g. buffer up all records but only dump when
  * getting a WARN or above.
- *
- * @param {Object} options contains the parameters:
+ * @public
+ * @class
+ * @param {Object} opts contains the parameters:
  *      - {Object} stream The stream to which to write when dumping captured
  *        records. One of `stream` or `streams` must be specified.
  *      - {Array} streams One of `stream` or `streams` must be specified.
@@ -102,6 +111,13 @@ function RequestCaptureStream(opts) {
 util.inherits(RequestCaptureStream, Stream);
 
 
+/**
+ * write to the stream
+ * @public
+ * @function write
+ * @param    {Object}    record a bunyan log record
+ * @returns  {undefined}
+ */
 RequestCaptureStream.prototype.write = function write(record) {
     var req_id = record.req_id || DEFAULT_REQ_ID;
     var ring;
@@ -163,6 +179,12 @@ RequestCaptureStream.prototype.write = function write(record) {
 };
 
 
+/**
+ * toString() serialization
+ * @public
+ * @function toString
+ * @returns  {String}
+ */
 RequestCaptureStream.prototype.toString = function toString() {
     return (sprintf(STR_FMT,
         this.constructor.name,
@@ -174,6 +196,22 @@ RequestCaptureStream.prototype.toString = function toString() {
 
 ///--- Serializers
 
+var SERIALIZERS = {
+    err: bunyan.stdSerializers.err,
+    req: bunyan.stdSerializers.req,
+    res: bunyan.stdSerializers.res,
+    client_req: clientReq,
+    client_res: clientRes
+};
+
+
+/**
+ * a request serializer. returns a stripped down object for logging.
+ * @private
+ * @function clientReq
+ * @param    {Object} req the request object
+ * @returns  {Object}
+ */
 function clientReq(req) {
     if (!req) {
         return (req);
@@ -197,6 +235,13 @@ function clientReq(req) {
 }
 
 
+/**
+ * a response serializer. returns a stripped down object for logging.
+ * @private
+ * @function clientRes
+ * @param    {Object} res the response object
+ * @returns  {Object}
+ */
 function clientRes(res) {
     if (!res || !res.statusCode) {
         return (res);
@@ -209,38 +254,40 @@ function clientRes(res) {
 }
 
 
-var SERIALIZERS = {
-    err: bunyan.stdSerializers.err,
-    req: bunyan.stdSerializers.req,
-    res: bunyan.stdSerializers.res,
-    client_req: clientReq,
-    client_res: clientRes
-};
+/**
+ * create a bunyan logger
+ * @public
+ * @function createLogger
+ * @param    {String}     name of the logger
+ * @returns  {Object}          bunyan logger
+ */
+function createLogger(name) {
+    return (bunyan.createLogger({
+        name: name,
+        serializers: SERIALIZERS,
+        streams: [
+            {
+                level: 'warn',
+                stream: process.stderr
+            },
+            {
+                level: 'debug',
+                type: 'raw',
+                stream: new RequestCaptureStream({
+                    stream: process.stderr
+                })
+            }
+        ]
+    }));
+}
+
 
 
 ///--- Exports
 
 module.exports = {
     RequestCaptureStream: RequestCaptureStream,
     serializers: SERIALIZERS,
+    createLogger: createLogger
 
-    createLogger: function createLogger(name) {
-        return (bunyan.createLogger({
-            name: name,
-            serializers: SERIALIZERS,
-            streams: [
-                {
-                    level: 'warn',
-                    stream: process.stderr
-                },
-                {
-                    level: 'debug',
-                    type: 'raw',
-                    stream: new RequestCaptureStream({
-                        stream: process.stderr
-                    })
-                }
-            ]
-        }));
-    }
 };

lib/errors/http_error.js

@@ -20,6 +20,14 @@ var slice = Function.prototype.call.bind(Array.prototype.slice);
 
 ///--- Helpers
 
+/**
+ * used to programatically create http error code names, using the underlying
+ * status codes names exposed via the http module.
+ * @private
+ * @function codeToErrorName
+ * @param    {Number} code the http error code to dynamically create
+ * @returns  {String}
+ */
 function codeToErrorName(code) {
     code = parseInt(code, 10);
     var status = http.STATUS_CODES[code];
@@ -47,6 +55,12 @@ function codeToErrorName(code) {
 
 ///--- Error Base class
 
+/**
+ * HttpError class. inherits from WError.
+ * @public
+ * @class
+ * @param {Object} options an options object
+ */
 function HttpError(options) {
     assert.object(options, 'options');
 

lib/formatters/binary.js

@@ -4,6 +4,15 @@
 
 ///--- Exports
 
+/**
+ * binary formatter.
+ * @public
+ * @function formatBinary
+ * @param    {Object} req  the request object
+ * @param    {Object} res  the response object
+ * @param    {Object} body response body
+ * @returns  {Buffer}
+ */
 function formatBinary(req, res, body) {
     if (body instanceof Error) {
         res.statusCode = body.statusCode || 500;

lib/formatters/json.js

@@ -4,6 +4,15 @@
 
 ///--- Exports
 
+/**
+ * JSON formatter.
+ * @public
+ * @function formatJSON
+ * @param    {Object} req  the request object
+ * @param    {Object} res  the response object
+ * @param    {Object} body response body
+ * @returns  {String}
+ */
 function formatJSON(req, res, body) {
     if (body instanceof Error) {
         // snoop for RestError or HttpError, but don't rely on

lib/formatters/jsonp.js

@@ -4,6 +4,15 @@
 
 ///--- Exports
 
+/**
+ * JSONP formatter. like JSON, but with a callback invocation.
+ * @public
+ * @function formatJSONP
+ * @param    {Object} req  the request object
+ * @param    {Object} res  the response object
+ * @param    {Object} body response body
+ * @returns  {String}
+ */
 function formatJSONP(req, res, body) {
     if (!body) {
         res.setHeader('Content-Length', 0);

lib/formatters/text.js

@@ -4,6 +4,15 @@
 
 ///--- Exports
 
+/**
+ * JSONP formatter. like JSON, but with a callback invocation.
+ * @public
+ * @function formatJSONP
+ * @param    {Object} req  the request object
+ * @param    {Object} res  the response object
+ * @param    {Object} body response body
+ * @returns  {String}
+ */
 function formatText(req, res, body) {
     if (body instanceof Error) {
         res.statusCode = body.statusCode || 500;

lib/http_date.js

@@ -2,6 +2,14 @@
 
 'use strict';
 
+/**
+ * takes an instance of a date object, formats it UTC
+ *     e.g., Wed, 17 Jun 2015 01:30:26 GMT
+ * @public
+ * @function httpDate
+ * @param    {Object} now a date object
+ * @returns  {String}     formatted dated object
+ */
 module.exports = function httpDate(now) {
     if (!now) {
         now = new Date();

lib/index.js

@@ -12,6 +12,13 @@
 var shallowCopy = require('./utils').shallowCopy;
 
 
+/**
+ * creates a HttpClient or a flavor of it.
+ * @public
+ * @function createClient
+ * @param    {Object} options an options object
+ * @returns  {HttpClient | JsonClient | StringClient}
+ */
 function createClient(options) {
     if (typeof (options) === 'string') {
         options = {
@@ -51,6 +58,13 @@ function createClient(options) {
 }
 
 
+/**
+ * creates a json httpclient.
+ * @public
+ * @function createJsonClient
+ * @param    {Object}     options an options object
+ * @returns  {JsonClient}         a json client
+ */
 function createJsonClient(options) {
     if (typeof (options) === 'string') {
         options = {
@@ -64,6 +78,13 @@ function createJsonClient(options) {
 }
 
 
+/**
+ * creates a string httpclient.
+ * @public
+ * @function createStringClient
+ * @param    {Object}       options an options object
+ * @returns  {StringClient}         a string client
+ */
 function createStringClient(options) {
     if (typeof (options) === 'string') {
         options = {
@@ -77,6 +98,13 @@ function createStringClient(options) {
 }
 
 
+/**
+ * creates a regular httpclient.
+ * @public
+ * @function createHttpClient
+ * @param    {Object}     options an options object
+ * @returns  {HttpClient}         an http client
+ */
 function createHttpClient(options) {
     if (typeof (options) === 'string') {
         options = {
@@ -90,6 +118,13 @@ function createHttpClient(options) {
 }
 
 
+/**
+ * creates a server.
+ * @public
+ * @function createServer
+ * @param    {Object} options an options object
+ * @returns  {Server}
+ */
 function createServer(options) {
     var bunyan = require('./bunyan_helper');
     var InternalError = require('./errors').InternalError;
@@ -123,8 +158,11 @@ function createServer(options) {
  * parameters filled in by the passed hash.
  *
  * If a key is not found in the hash for a param, it is left alone.
- *
- * @param {Object} a hash of parameter names to values for substitution.
+ * @public
+ * @function realizeUrl
+ * @param   {String} pattern a url string
+ * @param   {Object} params  a hash of parameter names to values for substitution
+ * @returns {String}
  */
 function realizeUrl(pattern, params) {
     var p = pattern.replace(/\/:([^/]+)/g, function (match, k) {

lib/plugins/accept.js

@@ -15,9 +15,11 @@ var NotAcceptableError = require('../errors').NotAcceptableError;
  * Note you can get the set of types allowed from a restify server by doing
  * `server.acceptable`.
  *
- * @param {String} array of accept types.
- * @return {Function} restify handler.
- * @throws {TypeError} on bad input
+ * @public
+ * @function acceptParser
+ * @throws   {NotAcceptableError}
+ * @param    {String}    acceptable array of accept types.
+ * @returns  {Function}             restify handler.
  */
 function acceptParser(acceptable) {
     if (!Array.isArray(acceptable)) {

lib/plugins/audit.js

@@ -18,8 +18,10 @@ var HttpError = require('../errors').HttpError;
  *
  * This logs at the INFO level.
  *
- * @param {Object} options at least a bunyan logger (log).
- * @return {Function} to be used in server.after.
+ * @public
+ * @function auditLogger
+ * @param   {Object}   options at least a bunyan logger (log).
+ * @returns {Function}         to be used in server.after.
  */
 function auditLogger(options) {
     assert.object(options, 'options');