refactor: add inline comments

Author: h2non

index.js

@@ -1,68 +1,120 @@
 const Toxy = require('./lib/toxy')
-const rules = require('./lib/rules')
-const poisons = require('./lib/poisons')
 
 /**
- * API factory
+ * Expose `Toxy` API factory
+ *
+ * @exports {Function}
  */
 
 module.exports = Toxy
 
 /**
- * Expose internal modules as static members
+ * Exposes admin HTTP server constructor.
+ *
+ * @property {Function} admin
+ * @static
  */
 
 Toxy.admin = require('./lib/admin')
+
+/**
+ * Exposes Rule constructor.
+ *
+ * @property {Rule} Rule
+ * @static
+ */
+
 Toxy.Rule = require('./lib/rule')
+
+/**
+ * Exposes Base object.
+ *
+ * @property {Object} Base
+ * @static
+ */
+
 Toxy.Base = require('./lib/base')
+
+/**
+ * Exposes Poison constructor.
+ *
+ * @property {Poison} Poison
+ * @static
+ */
+
 Toxy.Poison = require('./lib/poison')
+
+/**
+ * Exposes Directive constructor.
+ *
+ * @property {Directive} Directive
+ * @static
+ */
+
 Toxy.Directive = require('./lib/directive')
+
+/**
+ * Exposes Rocky proxy constructor.
+ *
+ * @property {Rocky} Rocky
+ * @static
+ */
+
 Toxy.Rocky = require('rocky').Rocky
 
 /**
- * Expose current version
+ * Expose current version.
+ *
+ * @property {String} VERSION
+ * @static
  */
 
 Toxy.VERSION = require('./package.json').version
 
 /**
- * Expose built-in poisons
+ * Expose built-in poisons.
+ *
+ * @property {Object} rules
+ * @static
  */
 
-Toxy.poisons = Toxy.prototype.poisons = Object.create(null)
-
-poisons.forEach(function (poison) {
-  Toxy.poisons[poison.name] = function () {
-    return poison.apply(null, arguments)
-  }
-})
+Toxy.poisons = Toxy.prototype.poisons
 
 /**
- * Expose built-in rules
+ * Expose built-in rules.
+ *
+ * @property {Object} rules
+ * @static
  */
 
-Toxy.rules = Toxy.prototype.rules = Object.create(null)
-
-rules.forEach(function (rule) {
-  Toxy.rules[rule.name] = function () {
-    return rule.apply(null, arguments)
-  }
-})
+Toxy.rules = Toxy.prototype.rules
 
 /**
- * Extend built-in rules
+ * Attaches a new rule.
+ *
+ * @param {Function} poison
+ * @method addPoison
+ * @static
  */
 
 Toxy.addRule = addDirective('rules')
 
 /**
- * Extend built-in poisons
+ * Attaches a new poison.
+ *
+ * @param {Function} poison
+ * @method addPoison
+ * @static
  */
 
 Toxy.addPoison = addDirective('poisons')
 
 /**
- * Add directive helper
+ * Add directive helper.
+ *
+ * @param {String}
+ * @function addDirective
+ * @private
  */
 
 function addDirective (type) {

lib/toxy.js

@@ -1,5 +1,7 @@
 const midware = require('midware')
 const Proxy = require('./proxy')
+const rules = require('./lib/rules')
+const poisons = require('./lib/poisons')
 const randomId = require('./helpers').randomId
 
 module.exports = Toxy
@@ -24,17 +26,41 @@ function Toxy (opts) {
   setupMiddleware(this)
 }
 
+/**
+ * Default TCP port to listen.
+ *
+ * @property {Number} PORT
+ * @static
+ */
+
 Toxy.PORT = +process.env.PORT || 3000
 
 Toxy.prototype = Object.create(Proxy.prototype)
 
+/**
+ * Starts listening on the network in the given port and host.
+ *
+ * @param {Number} port
+ * @param {String} host
+ * @method listen
+ */
+
 Toxy.prototype.listen = function (port, host) {
   this.host = host
   this.port = +port || Toxy.PORT
   Proxy.prototype.listen.call(this, this.port, host)
   return this
 }
 
+/**
+ * Registers a new route in the proxy server.
+ *
+ * @param {String} method
+ * @param {String} path
+ * @return {Route}
+ * @method route
+ */
+
 Toxy.prototype.route = function (method, path) {
   const route = Proxy.prototype.route.apply(this, arguments)
 
@@ -59,6 +85,15 @@ Toxy.prototype.route = function (method, path) {
   return route
 }
 
+/**
+ * Finds and returns an already registered route in the router stack.
+ *
+ * @param {String} routeId
+ * @param {String} method
+ * @return {Route}
+ * @method findRoute
+ */
+
 Toxy.prototype.findRoute = function (routeId, method) {
   if (method) routeId = randomId(method, routeId)
 
@@ -71,6 +106,38 @@ Toxy.prototype.findRoute = function (routeId, method) {
   return routes.shift()
 }
 
+/**
+ * Expose built-in poisons.
+ *
+ * @property {Object} poisons
+ */
+
+Toxy.prototype.poisons = Object.create(null)
+
+poisons.forEach(function (poison) {
+  Toxy.prototype.poisons[poison.name] = function () {
+    return poison.apply(null, arguments)
+  }
+})
+
+/**
+ * Expose built-in rules.
+ *
+ * @property {Object} rules
+ */
+
+Toxy.prototype.rules = Object.create(null)
+
+rules.forEach(function (rule) {
+  Toxy.prototype.rules[rule.name] = function () {
+    return rule.apply(null, arguments)
+  }
+})
+
+/**
+ * Private helpers
+ */
+
 function finalHandler (route) {
   var isFinalHandler = false
   route.use(function (req, res, next) {