Refactoring

Author: chdanielmueller

lib/index.js

@@ -1,120 +1,98 @@
+/** @module index */
 'use strict';
 
-var doctrine = require('doctrine');
+
+// Dependencies
 var fs = require('fs');
-var jsYaml = require('js-yaml');
 var path = require('path');
+var doctrine = require('doctrine');
+var jsYaml = require('js-yaml');
 var swaggerTools = require('swagger-tools');
 
-// This is the Swagger object that conforms to the Swagger 2.0 specification.
-module.exports.swaggerObject = [];
-
-
 
 /**
- *  Parses the jsDoc comments from JavaScript source code.
- *  @param {string} sourceCode - Source code to parse
- *  @returns {array}
+ * Parses the provided API file for JSDoc comments.
+ * @function
+ * @param {string} file - File to be parsed
+ * @returns {array} JSDoc comments
+ * @requires doctrine
  */
-function parseJsDoc(jsSourceCode) {
+function parseApiFile(file) {
+  var fileExtension = path.extname(file);
+
+  if (fileExtension !== '.js') {
+    throw new Error('Unsupported extension \'' + fileExtension + '\'.');
+  }
+
   var jsDocRegex = /\/\*\*([\s\S]*?)\*\//gm;
-  var fragments = jsSourceCode.match(jsDocRegex);
-  var jsDocs = [];
-
-  if (fragments) {
-    for (var i = 0; i < fragments.length; i = i + 1) {
-      var fragment = fragments[i];
-      var jsDoc = doctrine.parse(fragment, {
-        unwrap: true,
-      });
-      jsDocs.push(jsDoc);
+  var fileContent = fs.readFileSync(file, { encoding: 'utf8' });
+  var regexResults = fileContent.match(jsDocRegex);
+
+  var jsDocComments = [];
+  if (regexResults) {
+    for (var i = 0; i < regexResults.length; i = i + 1) {
+      var jsDocComment = doctrine.parse(regexResults[i], { unwrap: true });
+      jsDocComments.push(jsDocComment);
     }
   }
 
-  return jsDocs;
+  return jsDocComments;
 }
 
 
-
-
 /**
- * Filter out jsDoc comments that do not have '@swagger' tag
- * and parses the YAML description of those that do.
- * @param {array} jsDocs - jsDoc comments
- * @returns {array}
+ * Filters JSDoc comments for those tagged with '@swagger'
+ * @function
+ * @param {array} jsDocComments - JSDoc comments
+ * @returns {array} JSDoc comments tagged with '@swagger'
+ * @requires js-yaml
  */
-function filterSwaggerTags(jsDocs) {
-  var swaggerJsDocs = [];
+function filterJsDocComments(jsDocComments) {
+  var swaggerJsDocComments = [];
 
-  for (var i = 0; i < jsDocs.length; i = i + 1) {
-    var jsDoc = jsDocs[i];
-    for (var j = 0; j < jsDoc.tags.length; j = j + 1) {
-      var tag = jsDoc.tags[j];
+  for (var i = 0; i < jsDocComments.length; i = i + 1) {
+    var jsDocComment = jsDocComments[i];
+    for (var j = 0; j < jsDocComment.tags.length; j = j + 1) {
+      var tag = jsDocComment.tags[j];
       if (tag.title === 'swagger') {
-        swaggerJsDocs.push(jsYaml.safeLoad(tag.description));
+        swaggerJsDocComments.push(jsYaml.safeLoad(tag.description));
       }
     }
   }
 
-  return swaggerJsDocs;
+  return swaggerJsDocComments;
 }
 
+
 /**
- *  Parse the JSDoc comments from a JavaScript file.
- *  @param {string} file - File to parse
+ * Adds the data in the Swagger JSDoc comments to the swagger object.
+ * @function
+ * @param {object} swaggerObject - Swagger object which will be written to
+ * @param {array} swaggerJsDocComments - JSDoc comments tagged with '@swagger'
  */
-function parseJsFile(file) {
-  var sourceCode = fs.readFileSync(file, {
-    encoding: 'utf8',
-  });
-  var jsDocComments = parseJsDoc(sourceCode);
-  var swaggerJsDocComments = filterSwaggerTags(jsDocComments);
-
-  // Attach the findings to the Swagger object.
+function addDataToSwaggerObject(swaggerObject, swaggerJsDocComments) {
   for (var i = 0; i < swaggerJsDocComments.length; i = i + 1) {
-    var paths = swaggerJsDocComments[i];
-    var propertyNames = Object.getOwnPropertyNames(paths);
+    var pathObject = swaggerJsDocComments[i];
+    var propertyNames = Object.getOwnPropertyNames(pathObject);
 
     for (var j = 0; j < propertyNames.length; j = j + 1) {
       var propertyName = propertyNames[j];
-      module.exports.swaggerObject.paths[propertyName] = paths[propertyName];
+      swaggerObject.paths[propertyName] = pathObject[propertyName];
     }
   }
 }
 
-/**
- *  Parses the provided API file and attaches the fields to the Swagger object.
- *  @param {string} file - File to be parsed
- */
-function parseApiFile(file) {
-  var fileExtension = path.extname(file);
-
-  if (fileExtension === '.js') {
-    parseJsFile(file);
-  } else {
-    throw new Error('Unsupported extension \'' + fileExtension + '\'.');
-  }
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
 
+// This is the Swagger object that conforms to the Swagger 2.0 specification.
+module.exports.swaggerObject = [];
 
 
 /**
- *  Initializes the module. This is intended to be called only once.
- *  @param {object} app - Express application
- *  @param {object} options - Configuration options
+ * Initializes the module. This is intended to be called only once.
+ * @function
+ * @param {object} app - Express application
+ * @param {object} options - Configuration options
+ * @requires swagger-tools
  */
 module.exports.init = function(app, options) {
   if (!options) {
@@ -132,7 +110,9 @@ module.exports.init = function(app, options) {
 
   // Parse the documentation in the APIs array.
   for (var i = 0; i < options.apis.length; i = i + 1) {
-    parseApiFile(options.apis[i]);
+    var jsDocComments = parseApiFile(options.apis[i]);
+    var swaggerJsDocComments = filterJsDocComments(jsDocComments);
+    addDataToSwaggerObject(module.exports.swaggerObject, swaggerJsDocComments);
   }
 
   var swaggerToolsUIOptions = {