feat: add support for additionalTagNames (#23)

* Test all JSDOC 3 tags.

* Add support for additional tag names.

Fixes #15.

* Add documentation for configuring additionalTagNames

Author: jschaf

.README/README.md

@@ -98,6 +98,24 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+
+### Additional Tag Names
+
+Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "additionalTagNames": {
+                "customTags": ["define", "extends", "record"]
+            }
+        }
+    }
+}
+```
+
 ## Rules
 
 {"gitdown": "include", "file": "./rules/check-param-names.md"}

src/iterateJsdoc.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import commentParser from 'comment-parser';
 import jsdocUtils from './jsdocUtils';
 
-const curryUtils = (functionNode, jsdoc, tagNamePreference) => {
+const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames) => {
     const utils = {};
 
     utils.getFunctionParameterNames = () => {
@@ -22,7 +22,7 @@ const curryUtils = (functionNode, jsdoc, tagNamePreference) => {
     };
 
     utils.isValidTag = (name) => {
-        return jsdocUtils.isValidTag(name);
+        return jsdocUtils.isValidTag(name, additionalTagNames);
     };
 
     utils.hasTag = (name) => {
@@ -36,6 +36,7 @@ export default (iterator) => {
     return (context) => {
         const sourceCode = context.getSourceCode();
         const tagNamePreference = _.get(context, 'settings.jsdoc.tagNamePreference') || {};
+        const additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
 
         const checkJsdoc = (functionNode) => {
             const jsdocNode = sourceCode.getJSDocComment(functionNode);
@@ -63,7 +64,7 @@ export default (iterator) => {
                 context.report(jsdocNode, message);
             };
 
-            const utils = curryUtils(functionNode, jsdoc, tagNamePreference);
+            const utils = curryUtils(functionNode, jsdoc, tagNamePreference, additionalTagNames);
 
             iterator({
                 context,

src/jsdocUtils.js

@@ -66,10 +66,12 @@ const getPreferredTagName = (name : string, tagPreference : Object = {}) : strin
     return _.has(tagPreference, name) ? tagPreference[name] : name;
 };
 
-const isValidTag = (name : string) : boolean => {
+const isValidTag = (name : string, additionalTagNames : Object) : boolean => {
     const validTagNames = _.keys(tagNames).concat(_.flatten(_.values(tagNames)));
+    const additionalTags = additionalTagNames.customTags || [];
+    const allTags = validTagNames.concat(additionalTags);
 
-    return _.includes(validTagNames, name);
+    return _.includes(allTags, name);
 };
 
 const hasTag = (jsdoc : Object, targetTagName : string) : boolean => {

tests/jsdocUtils.js

@@ -27,17 +27,22 @@ describe('jsdocUtils', () => {
     describe('isValidTag()', () => {
         context('tag is invalid', () => {
             it('returns false', () => {
-                expect(jsdocUtils.isValidTag('foo')).to.equal(false);
+                expect(jsdocUtils.isValidTag('foo', {})).to.equal(false);
             });
         });
         context('tag is valid', () => {
             it('returns true', () => {
-                expect(jsdocUtils.isValidTag('param')).to.equal(true);
+                expect(jsdocUtils.isValidTag('param', {})).to.equal(true);
             });
         });
         context('tag is valid alias', () => {
             it('returns true', () => {
-                expect(jsdocUtils.isValidTag('arg')).to.equal(true);
+                expect(jsdocUtils.isValidTag('arg', {})).to.equal(true);
+            });
+        });
+        context('tag is valid and customized', () => {
+            it('returns true', () => {
+                expect(jsdocUtils.isValidTag('foobar', {customTags: ['foobar']})).to.equal(true);
             });
         });
     });

tests/rules/assertions/checkTagNames.js

@@ -1,5 +1,9 @@
 /* eslint-disable no-restricted-syntax */
 
+import JSDOC_3_TAGS from './jsdoc3Tags';
+
+const ALL_JSDOC_TAGS_COMMENT = '/** \n * @' + JSDOC_3_TAGS.join('\n * @') + '\n */';
+
 export default {
     invalid: [
         {
@@ -68,7 +72,67 @@ export default {
                     }
                 }
             }
-        }
+        },
+        {
+            code: `
+                /**
+                 * @bar foo
+                 */
+                function quux (foo) {
+
+                }
+            `,
+            errors: [
+                {
+                    message: 'Invalid JSDoc tag name "bar".'
+                }
+            ],
+        },
+        {
+            code: `
+                /**
+                 * @baz @bar foo
+                 */
+                function quux (foo) {
+
+                }
+            `,
+            errors: [
+                {
+                    message: 'Invalid JSDoc tag name "baz".'
+                }
+            ],
+            settings: {
+                jsdoc: {
+                    additionalTagNames: {
+                        customTags: ['bar']
+                    }
+                }
+            }
+        },
+        {
+            code: `
+                /**
+                 * @bar
+                 * @baz
+                 */
+                function quux (foo) {
+
+                }
+            `,
+            errors: [
+                {
+                    message: 'Invalid JSDoc tag name "baz".'
+                }
+            ],
+            settings: {
+                jsdoc: {
+                    additionalTagNames: {
+                        customTags: ['bar']
+                    }
+                }
+            }
+        },
     ],
     valid: [
         {
@@ -97,6 +161,43 @@ export default {
                     }
                 }
             }
+        },
+        {
+            code: `
+                /**
+                 * @bar foo
+                 */
+                function quux (foo) {
+
+                }
+            `,
+            settings: {
+                jsdoc: {
+                    additionalTagNames: {
+                        customTags: ['bar']
+                    }
+                }
+            }
+        },
+        {
+            code: `
+                /**
+                 * @baz @bar foo
+                 */
+                function quux (foo) {
+
+                }
+            `,
+            settings: {
+                jsdoc: {
+                    additionalTagNames: {
+                        customTags: ['baz', 'bar']
+                    }
+                }
+            }
+        },
+        {
+            code: ALL_JSDOC_TAGS_COMMENT + '\n' + 'function quux (foo) {}',
         }
     ]
 };

tests/rules/assertions/jsdoc3Tags.js

@@ -0,0 +1,64 @@
+export default [
+    'abstract',
+    'access',
+    'alias',
+    'augments',
+    'author',
+    'borrows',
+    'callback',
+    'class',
+    'classdesc',
+    'constant',
+    'constructs',
+    'copyright',
+    'default',
+    'deprecated',
+    'description',
+    'enum',
+    'event',
+    'example',
+    'exports',
+    'external',
+    'file',
+    'fires',
+    'function',
+    'global',
+    'ignore',
+    'implements',
+    'inheritdoc',
+    'inner',
+    'instance',
+    'interface',
+    'kind',
+    'lends',
+    'license',
+    'listens',
+    'member',
+    'memberof',
+    'mixes',
+    'mixin',
+    'module',
+    'name',
+    'namespace',
+    'override',
+    'param',
+    'private',
+    'property',
+    'protected',
+    'public',
+    'readonly',
+    'requires',
+    'returns',
+    'see',
+    'since',
+    'static',
+    'summary',
+    'this',
+    'throws',
+    'todo',
+    'tutorial',
+    'type',
+    'typedef',
+    'variation',
+    'version'
+];