checkAnnotations: rework

- true now means existance of tag
- added 'some' value to force some value in tag
- patched tests for changed tag values
- changed @access value to 'some'

Fixes #74

Author: Alexej Yaroshevich

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

@@ -70,7 +70,6 @@ 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] !== '*') {
@@ -86,17 +85,30 @@ function validateAnnotations(file, errors) {
         node.iterate(function(tag) {
             if (!(tag.id in tags)) {
                 errors.add('unavailable tag ' + tag.id, 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);
+            switch (tags[tag.id]) {
+                case false:
+                    if (isFilled) {
+                        errors.add('unexpected data in tag ' + tag.id, tag.loc);
+                    }
+                    break;
+
+                case true:
+                    // any data
+                    break;
+
+                case 'some':
+                    if (!isFilled) {
+                        errors.add('incomplete data in tag ' + tag.id, tag.loc);
+                    }
+                    break;
+
+                default:
+                    // unknown
             }
         });
     });

lib/tags/jsdoc3.json

@@ -1,6 +1,6 @@
 {
     "abstract": false,
-    "access": true,
+    "access": "some",
     "alias": true,
     "arg": true,
     "argument": true,

test/lib/jsdoc.js

@@ -131,11 +131,14 @@ describe('jsdoc', function() {
                 ' * @param {Type} some long\n' +
                 ' *   description of param\n' +
                 ' * @abstract\n' +
+                ' * @example\n' +
+                ' * // use this anywhere\n' +
+                ' * makeFun(value, some);\n' +
                 ' */', {start: {line: 5, column: 2}});
         });
 
         it('should parses comment and create all tags and types', function() {
-            expect(c1.tags.length).to.eq(3);
+            expect(c1.tags.length).to.eq(4);
 
             var tag1 = c1.tags[0];
             expect(tag1.id).to.eq('tag1');
@@ -154,6 +157,12 @@ describe('jsdoc', function() {
             var abs = c1.tags[2];
             expect(abs.id).to.eq('abstract');
             expect(abs.loc).to.eql(new Location(11, 5));
+
+            var example = c1.tags[3];
+            expect(example.id).to.eq('example');
+            expect(example.type).to.eq(undefined);
+            expect(example.name).to.eq(undefined);
+            expect(example.description).to.eq('// use this anywhere\nmakeFun(value, some);');
         });
 
     });

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

@@ -39,6 +39,17 @@ describe('lib/rules/validate-jsdoc/check-annotations', function() {
                 code: function() {
                     /** @access */
                 }
+            },
+            {
+                it: 'should not throw example tag',
+                errors: [],
+                code: function() {
+                    /**
+                     * @example
+                     * // some sample comment
+                     * aFunctionSampleCall({a:1, b:2, c:3, e:null}, {a:4, d:5}, {b:6, c:7});
+                    */
+                }
             }
             /* jshint ignore:end */
         ]);
@@ -73,7 +84,7 @@ describe('lib/rules/validate-jsdoc/check-annotations', function() {
             'preset': 'jsdoc3',
             'extra': {
                 'empty': false,
-                'fulfilled': true
+                'fulfilled': 'some'
             }
         }});
 
@@ -115,7 +126,7 @@ describe('lib/rules/validate-jsdoc/check-annotations', function() {
         checker.cases([
             /* jshint ignore:start */
             {
-                it: 'should throw',
+                it: 'arg, argument tags should throw',
                 errors: 2,
                 code: function() {
                     /**