Merge pull request #836 from DonutEspresso/jsdoc

jsdoc comments
restify · Jun 17, 2015 · be86556 · be86556
2 parents d2ca569 + 00ed023
commit be86556
Show file tree

Hide file tree

Showing 38 changed files with 1,033 additions and 161 deletions.
diff --git a/.eslintrc b/.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

diff --git a/lib/bunyan_helper.js b/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,19 +51,20 @@ 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:
- *      - {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.
- *      - {Number|String} level The level at which to trigger dumping captured
- *        records. Defaults to bunyan.WARN.
- *      - {Number} maxRecords Number of records to capture. Default 100.
- *      - {Number} maxRequestIds Number of simultaneous request id capturing
- *        buckets to maintain. Default 1000.
- *      - {Boolean} dumpDefault If true, then dump captured records on the
- *        *default* request id when dumping. I.e. dump records logged without
- *        a "req_id" field. Default false.
+ * @public
+ * @class
+ * @param {Object} opts                contains the parameters:
+ * @param {Object} opts.stream         The stream to which to write when dumping captured
+ *                                     records. One of `stream` or `streams` must be specified.
+ * @param {Array} opts.streams         One of `stream` or `streams` must be specified.
+ * @param {Number | String} opts.level The level at which to trigger dumping captured
+ *                                     records. Defaults to bunyan.WARN.
+ * @param {Number} opts.maxRecords     Number of records to capture. Default 100.
+ * @param {Number} opts.maxRequestIds  Number of simultaneous request id capturing
+ *                                     buckets to maintain. Default 1000.
+ * @param {Boolean} opts.dumpDefault   If true, then dump captured records on the
+ *                                     *default* request id when dumping. I.e. dump records logged without
+ *                                     "req_id" field. Default false.
  */
 function RequestCaptureStream(opts) {
     assert.object(opts, 'options');
@@ -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
-                    })
-                }
-            ]
-        }));
-    }
 };
diff --git a/lib/errors/http_error.js b/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');
 

diff --git a/lib/formatters/binary.js b/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;

diff --git a/lib/formatters/json.js b/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

diff --git a/lib/formatters/jsonp.js b/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);

diff --git a/lib/formatters/text.js b/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;

diff --git a/lib/http_date.js b/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();

diff --git a/lib/index.js b/lib/index.js
@@ -12,6 +12,15 @@
 var shallowCopy = require('./utils').shallowCopy;
 
 
+/**
+ * creates an http request client. based on options passed in, will create one
+ * of three existing clients: Http, String, or Json.
+ * @public
+ * @function createClient
+ * @param    {Object} options      an options object
+ * @param    {String} options.type 'http' | 'json' | 'string'
+ * @returns  {HttpClient | JsonClient | StringClient}
+ */
 function createClient(options) {
     if (typeof (options) === 'string') {
         options = {
@@ -51,6 +60,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 +80,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 +100,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 +120,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 +160,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) {