Merge pull request #214 from dwyl/inch-ci-documentation-issue-203

add JSDoc comments to ALL the methods in /lib/index.js

README.md

@@ -9,8 +9,9 @@
 [![Build Status](https://travis-ci.org/dwyl/hapi-auth-jwt2.svg "Build Status = Tests Passing")](https://travis-ci.org/dwyl/hapi-auth-jwt2)
 [![codecov.io Code Coverage](https://img.shields.io/codecov/c/github/dwyl/hapi-auth-jwt2.svg?maxAge=2592000)](https://codecov.io/github/dwyl/hapi-auth-jwt2?branch=master)
 [![JavaScript Style Guide: Good Parts](https://img.shields.io/badge/code%20style-goodparts-brightgreen.svg?style=flat)](https://github.com/dwyl/goodparts "JavaScript The Good Parts")
+[![Inline docs](http://inch-ci.org/github/dwyl/hapi-auth-jwt2.svg?branch=master)](http://inch-ci.org/github/dwyl/hapi-auth-jwt2)
 [![Code Climate](https://codeclimate.com/github/dwyl/hapi-auth-jwt2/badges/gpa.svg "No Nasty Code")](https://codeclimate.com/github/dwyl/hapi-auth-jwt2)
-[![HAPI 15.0.3](http://img.shields.io/badge/hapi-15.0.3-brightgreen.svg "Latest Hapi.js")](http://hapijs.com)
+[![HAPI 15.2.0](http://img.shields.io/badge/hapi-15.2.0-brightgreen.svg "Latest Hapi.js")](http://hapijs.com)
 [![Node.js Version](https://img.shields.io/node/v/hapi-auth-jwt2.svg?style=flat "Node.js 10 & 12 and io.js latest both supported")](http://nodejs.org/download/)
 [![Dependency Status](https://david-dm.org/dwyl/hapi-auth-jwt2.svg "Dependencies Checked & Updated Regularly (Security is Important!)")](https://david-dm.org/dwyl/hapi-auth-jwt2)
 [![devDependencies Status](https://david-dm.org/dwyl/hapi-auth-jwt2/dev-status.svg)](https://david-dm.org/dwyl/hapi-auth-jwt2?type=dev)

lib/extract.js

@@ -47,7 +47,12 @@ module.exports = function extract (request, options) {
   return auth ? auth.replace(/Bearer/gi, '').replace(/ /g, '') : null;
 };
 
+/**
+ * isValid is a basic check for JWT validity of Token format http://git.io/xPBn
+ * @param {String} token - the token extracted from Header/Cookie/query
+ * @returns {Boolean} true|false - true if JWT is valid. false if invalid.
+ */
 module.exports.isValid = function isValid (token) {
- // rudimentary check for JWT validity see: http://git.io/xPBn for JWT format
+  
   return token.split('.').length === 3;
 };

lib/index.js

@@ -1,19 +1,33 @@
 'use strict';
 
-var Boom = require('boom'); // error handling https://github.com/hapijs/boom
-var assert = require('assert');
-var JWT = require('jsonwebtoken'); // https://github.com/docdis/learn-json-web-tokens
-var extract = require('./extract');    // extract token from Auth Header, URL or Coookie
-var pkg = require('../package.json');
-var internals = {}; // Declare internals >> see: http://hapijs.com/styleguide
+var Boom = require('boom');           // error handling https://github.com/hapijs/boom
+var assert = require('assert');       // use assert to check if options are set
+var JWT = require('jsonwebtoken');    // https://github.com/docdis/learn-json-web-tokens
+var extract = require('./extract');   // extract token from Auth Header, URL or Coookie
+var pkg = require('../package.json'); // use package name and version rom package.json
+var internals = {};                   // see: http://hapijs.com/styleguide#module-globals
 
+/**
+ * register registers the name and exposes the implementation of the plugin
+ * see: http://hapijs.com/api#serverplugins for plugin format
+ * @param {Object} server - the hapi server to which we are attaching the plugin
+ * @param {Object} options - any options set during plugin registration
+ * in this case we are not using the options during register but we do later.
+ * @param {Function} next - the callback called once registration succeeds
+ * @returns {Function} next - returns (calls) the callback when complete.
+ */
 exports.register = function (server, options, next) {
-  server.auth.scheme('jwt', internals.implementation);
-  next();
+  server.auth.scheme('jwt', internals.implementation); // hapijs.com/api#serverauthapi
+
+  return next();
 };
 
+/**
+ * attributes merely aliases the package.json (re-uses package name & version)
+ * simple example: github.com/hapijs/hapi/blob/master/API.md#serverplugins
+ */
 exports.register.attributes = { // hapi requires attributes for a plugin.
-  pkg: pkg                      // See: http://hapijs.com/tutorials/plugins
+  pkg: pkg                      // also see: http://hapijs.com/tutorials/plugins
 };
 
 /**
@@ -28,16 +42,27 @@ internals.isFunction = function (functionToCheck) {
     && getType.toString.call(functionToCheck) === '[object Function]';
 };
 
-internals.isArray = function (functionToCheck) {
+/**
+ * isArray checks if a given variable is an Array.
+ * @param {Object} variable - the value we want to confirm is an Array
+ * @returns {Boolean} - true if the variable is an Array.
+ */
+internals.isArray = function (variable) {
   var getType = {};
 
-  return functionToCheck
-    && getType.toString.call(functionToCheck) === '[object Array]';
+  return variable
+    && getType.toString.call(variable) === '[object Array]';
 };
-// function throwBoomError (ctx) {
-//   return Boom[ctx.errorType](ctx.message, ctx.scheme, ctx.attributes);
-// }
 
+/**
+ * implementation is the "main" interface to the plugin and contains all the
+ * "implementation details" (methods) such as authenicate, response & raiseError
+ * @param {Object} server - the Hapi.js server object we are attaching the
+ * the hapi-auth-jwt2 plugin to.
+ * @param {Object} options - any configuration options passed in.
+ * @returns {Function} authenicate - we return the authenticate method after
+ * registering the plugin as that's the method that gets called for each route.
+ */
 internals.implementation = function (server, options) {
   assert(options, 'options are required for jwt auth scheme'); // pre-auth checks
   assert(options.validateFunc
@@ -71,6 +96,14 @@ internals.implementation = function (server, options) {
   }
 
   return {
+    /**
+     * authenticate is the "work horse" of the plugin. it's the method that gets
+     * called every time a route is requested and needs to validate/verify a JWT
+     * @param {Object} request - the standard route handler request object
+     * @param {Object} reply - the standard hapi reply interface
+     * @returns {Boolean} if the JWT is valid we return a credentials object
+     * otherwise throw an error to inform the app & client of unauthorized req.
+     */
     authenticate: function (request, reply) {
       var token = extract(request, options); // extract token Header/Cookie/Query
       var tokenType = options.tokenType || 'Token'; // see: https://git.io/vXje9
@@ -176,6 +209,14 @@ internals.implementation = function (server, options) {
 
       return true;
     },
+    /**
+     * response is an Optional method called if an options.responseFunc is set.
+     * @param {Object} request - the standard route handler request object
+     * @param {Object} reply - the standard hapi reply interface ...
+     * after we run the custom options.responseFunc we reply.continue to execute
+     * the next plugin in the list.
+     * @returns {Boolean} true. always return true (unless there's an error...)
+     */
     response: function (request, reply) {
       if (options.responseFunc && typeof options.responseFunc === 'function') {
         options.responseFunc(request, reply, function (err) {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hapi-auth-jwt2",
-  "version": "7.2.2",
+  "version": "7.2.3",
   "description": "Hapi.js Authentication Plugin/Scheme using JSON Web Tokens (JWT)",
   "main": "lib/index.js",
   "repository": {