final steps

Author: Alexej Yaroshevich

lib/rules/validate-jsdoc/check-annotations.js

@@ -19,9 +19,20 @@ validateAnnotations.configure = function(options) {
 
     if (typeof o === 'string') {
         o = {preset: o};
+    } else if (typeof o === 'object') {
+        var oKeys = Object.keys(o);
+        oKeys.forEach(function(key) {
+            if (key === 'preset') {
+                assert(typeof o.preset === 'string', 'jsDoc.checkAnnotation.preset should be preset name');
+            } else if (key === 'extra') {
+                assert(typeof o[key] === 'object', 'jsDoc.checkAnnotation.preset should be `tag: fulfill` map');
+            } else {
+                throw new Error('jsDoc.checkAnnotation.' + key + ' is unsupported field');
+            }
+        });
     }
 
-    tags = {};
+    tags = Object.create ? Object.create(null) : {};
 
     if (o === true) {
         Object.keys(availablePresets).forEach(function(preset) {
@@ -33,15 +44,18 @@ validateAnnotations.configure = function(options) {
 
     } else if (typeof o === 'object') {
         if (o.preset) {
-            assert(typeof o.preset === 'string', 'jsDoc.checkAnnotation.preset should be preset name');
             assert(availablePresets[o.preset], 'Unknown tag preset ' + o.preset);
             Object.keys(availablePresets[o.preset]).forEach(function(tag) {
                 tags[tag] = tags[tag] || availablePresets[o.preset][tag];
             });
         }
         if (o.extra) {
             Object.keys(o.extra).forEach(function(tag) {
-                tags[tag] = o.extra[tag];
+                if (o.extra[tag] === null) {
+                    delete tags[tag];
+                } else {
+                    tags[tag] = o.extra[tag];
+                }
             });
         }
     }
@@ -53,6 +67,7 @@ validateAnnotations.configure = function(options) {
  * @param {JSCS.Errors} errors
  */
 function validateAnnotations(file, errors) {
+    var checkFulfill = true; //this._options.checkAnnotations.checkFulfill;
     var comments = file.getComments();
     comments.forEach(function(commentNode) {
         if (commentNode.type !== 'Block' || commentNode.value[0] !== '*') {
@@ -66,11 +81,19 @@ function validateAnnotations(file, errors) {
         }
 
         node.iterate(function(tag) {
-            if (!tags.hasOwnProperty[tag.id]) {
+            if (!(tag.id in tags)) {
                 errors.add('unavailable tag ' + tag.id, tag.loc);
             }
-            else if (tags[tag.id] && (!tag.name || !tag.type)) {
-                errors.add('incomplete tag ' + tag.id + ' data', tag.loc);
+            if (!checkFulfill) {
+                return;
+            }
+
+            // checking tag fullfill
+            var isFilled = tag.name || tag.type || tag.description;
+            if (tags[tag.id] === false && isFilled) {
+                errors.add('unexpected data in tag ' + tag.id, tag.loc);
+            } else if (tags[tag.id] === true && !isFilled) {
+                errors.add('incomplete data in tag ' + tag.id, tag.loc);
             }
         });
     });

test/lib/rules/validate-jsdoc/check-annotations.js

@@ -1,9 +1,9 @@
-describe('lib/rules/validate-jsdoc/check-annotations', function () {
+describe('lib/rules/validate-jsdoc/check-annotations', function() {
     var checker = global.checker({
         additionalRules: ['lib/rules/validate-jsdoc.js']
     });
 
-    describe('with true', function () {
+    describe('with true', function() {
         checker.rules({checkAnnotations: true});
 
         checker.cases([
@@ -16,10 +16,116 @@ describe('lib/rules/validate-jsdoc/check-annotations', function () {
                      * @ppublic
                      */
                 }
+            },
+            {
+                it: 'should not report valid tags',
+                code: function() {
+                    /** @const FOO */
+                    var FOO = 'bar';
+
+                    /**
+                     * @chainable
+                     * @abstract
+                     * @accessor
+                     * @param {string} message
+                     * @return {string}
+                     */
+                    function _f() {}
+                }
+            },
+            {
+                it: 'should throw @access without data',
+                errors: {message: 'incomplete data in tag access'},
+                code: function() {
+                    /** @access */
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
+    describe('with "jsduck5"', function() {
+        checker.rules({checkAnnotations: 'jsduck5'});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not throw @alternateClassName',
+                code: function() {
+                    /** @alternateClassName Vasya */
+                }
+            },
+            {
+                it: 'should throw unavailable @arg',
+                errors: {message: 'unavailable tag arg'},
+                code: function() {
+                    /**
+                     * @arg
+                     */
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
+    describe('with "jsdoc3" and extra tags', function() {
+        checker.rules({checkAnnotations: {
+            'preset': 'jsdoc3',
+            'extra': {
+                'empty': false,
+                'fulfilled': true
+            }
+        }});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not throw @boomer/@argument',
+                code: function() {
+                    /**
+                     * @empty
+                     * @fulfilled tag
+                     * @argument {String} jsdoc3 specific tag
+                     */
+                }
+            }, {
+                it: 'should throw invalid tags',
+                errors: 3,
+                code: function() {
+                    /**
+                     * @empty with value
+                     * @fulfilled
+                     * @alternateClassName {string}
+                     */
+                }
             }
             /* jshint ignore:end */
         ]);
+    });
+
+    describe('with "jsdoc3" and disabled @arg, @argument tags', function() {
+        checker.rules({checkAnnotations: {
+            'preset': 'jsdoc3',
+            'extra': {
+                'arg': null,
+                'argument': null
+            }
+        }});
 
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should throw',
+                errors: 2,
+                code: function() {
+                    /**
+                     * @arg {string}
+                     * @argument {string}
+                     */
+                }
+            }
+            /* jshint ignore:end */
+        ]);
     });
 
 });