From 0fdab7f58b1df929c7a8f51b8bb0ec6a99c6d197 Mon Sep 17 00:00:00 2001
From: "Jerome A. C. Ngo" <jeromengo@gmail.com>
Date: Wed, 25 Apr 2018 20:42:42 +0800
Subject: [PATCH] Add support for jsDoc filtering

---
 example/app.js |  9 +++++++++
 lib/index.js   | 10 +++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/example/app.js b/example/app.js
index f8359f00..074c2cba 100644
--- 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
index 9ed6b4aa..01aeea0e 100644
--- 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]);