Merge pull request #77 from jscs-dev/hotfix/check-annotations-rework

Check annotations rework and bunch of minor fixes

Author: qfox

README.md

@@ -73,14 +73,23 @@ There are 3 presets for `Closure Compiler`, `JSDoc3` and `JSDuck5`.
 
 By default it allows any tag of mixed set. You can pass `Object` to select preset with `preset` field and add custom tags with `extra` field.
 
-Type: `Boolean` or `String` or `{"preset": String, "extra": Object}` (`extra` field should contains tags in keys and boolean in values. false means no value possible)
+Type: `Boolean` or `String` or `{"preset": String, "extra": Object}` (see [tag values](#user-content-tag-values))
 
 Values: `true`, `"closurecompiler"`, `"jsdoc3"`, `"jsduck5"`, `Object`
 
 Context: `file`
 
 Tags: `*`
 
+#### Tag values
+
+`extra` field should contains tags in keys and there are options for values:
+- `false` means tag available with no value
+- `true` means tag available with any value
+- `"some"` means tag available and requires some value
+
+See also [tag presets](https://github.com/jscs-dev/jscs-jsdoc/tree/hotfix/check-annotations-rework/lib/tags).
+
 #### Example
 
 ```js

lib/jsdoc.js

@@ -420,7 +420,7 @@ function _iterateDocTypes(node, cb) {
  * Converts AST jsDoc node to simple object
  * @param {Object} node
  * @returns {!Array.<SimplifiedType>}
- * @link https://github.com/Kuniwak/jsdoctypeparser
+ * @see https://github.com/Kuniwak/jsdoctypeparser
  */
 function _simplifyType(node) {
     var res = [];

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/closurecompiler.json

@@ -3,54 +3,56 @@
     "author": true,
     "argument": true,
     "borrows": true,
-    "class": true,
+    "class": false,
     "const": false,
     "constant": false,
     "constructor": false,
     "constructs": false,
     "default": true,
-    "define": true,
+    "define": "some",
     "deprecated": true,
     "description": true,
     "dict": false,
-    "enum": true,
+    "enum": "some",
     "event": true,
     "example": true,
     "export": false,
-    "extends": true,
+    "extends": "some",
     "field": false,
     "fileOverview": true,
     "final": false,
     "function": false,
     "ignore": false,
-    "implements": true,
+    "implements": "some",
     "inheritDoc": false,
     "inner": false,
     "interface": false,
-    "lends": true,
-    "license": true,
-    "link": true,
+    "lends": "some",
+    "license": "some",
     "memberOf": true,
     "name": true,
     "namespace": true,
     "nosideeffects": false,
     "override": false,
     "package": false,
-    "param": true,
-    "preserve": true,
+    "param": "some",
+    "preserve": "some",
     "private": false,
     "property": true,
+    "protected": false,
     "public": false,
     "requires": true,
-    "returns": true,
+    "returns": "some",
+    "return": "some",
     "see": true,
     "since": true,
     "static": false,
     "struct": false,
     "template": true,
-    "this": true,
-    "throws": true,
-    "type": true,
-    "typedef": true,
-    "version": true
+    "this": "some",
+    "throws": "some",
+    "typedef": "some",
+    "type": "some",
+    "unrestricted": false,
+    "version": "some"
 }

lib/tags/jsdoc3.json

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

package.json

@@ -23,7 +23,7 @@
     "node": ">= 0.10.0"
   },
   "dependencies": {
-    "comment-parser": "^0.2.3",
+    "comment-parser": "zxqfox/comment-parser#jscs-jsdoc",
     "jsdoctypeparser": "^1.1.3"
   },
   "devDependencies": {

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() {
                     /**

test/mocha.opts

@@ -1,5 +1,6 @@
 test/*test*.js test/lib/
 --recursive
 --require test/init.js
+--timeout 6000
 -R dot
 -u bdd