Add support for jsDoc filtering

Surnet · Apr 25, 2018 · 0fdab7f · 0fdab7f
1 parent b091983
commit 0fdab7f
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 3 deletions.
diff --git a/example/app.js b/example/app.js
@@ -30,12 +30,21 @@ var swaggerDefinition = {
   basePath: '/', // Base path (optional)
 };
 
+// jsDocFilter has only one parameter - jsComment
+// jsComment contains the actual route jsDocumentation
+var jsDocFilter = function(jsComment) {
+  // Do anything here below just to filter out comments
+  // as long as the function returns boolean
+  return typeof jsComment !== 'undefined';
+};
+
 // Options for the swagger docs
 var options = {
   // Import swaggerDefinitions
   swaggerDefinition: swaggerDefinition,
   // Path to the API docs
   apis: ['./example/routes*.js', './example/parameters.yaml'],
+  jsDocFilter: jsDocFilter,
 };
 
 // Initialize swagger-jsdoc -> returns validated swagger spec in json format

diff --git a/lib/index.js b/lib/index.js
@@ -14,10 +14,11 @@ var swaggerHelpers = require('./swagger-helpers');
  * Parses the provided API file for JSDoc comments.
  * @function
  * @param {string} file - File to be parsed
+ * @param {object} jsDocFilter - Function returning boolean to filter docs
  * @returns {{jsdoc: array, yaml: array}} JSDoc comments and Yaml files
  * @requires doctrine
  */
-function parseApiFile(file) {
+function parseApiFile(file, jsDocFilter) {
   var jsDocRegex = /\/\*\*([\s\S]*?)\*\//gm;
   var fileContent = fs.readFileSync(file, { encoding: 'utf8' });
   var ext = path.extname(file);
@@ -31,7 +32,10 @@ function parseApiFile(file) {
     if (regexResults) {
       for (var i = 0; i < regexResults.length; i = i + 1) {
         var jsDocComment = doctrine.parse(regexResults[i], { unwrap: true });
-        jsDocComments.push(jsDocComment);
+
+        if (typeof jsDocFilter !== 'function' || !!jsDocFilter(jsDocComment)) {
+          jsDocComments.push(jsDocComment);
+        }
       }
     }
   }
@@ -102,7 +106,7 @@ module.exports = function(options) {
 
   // Parse the documentation in the APIs array.
   for (var i = 0; i < apiPaths.length; i = i + 1) {
-    var files = parseApiFile(apiPaths[i]);
+    var files = parseApiFile(apiPaths[i], options.jsDocFilter);
     var swaggerJsDocComments = filterJsDocComments(files.jsdoc);
 
     var problems = swaggerHelpers.findDeprecated([files, swaggerJsDocComments]);