doctrine2 - npm Package Compare versions

Comparing version 0.6.7 to 1.2.2

lib/doctrine.js

@@ -73,2 +73,6 @@ /*
 
+    function isReturnTitle(title) {
+        return title === 'return' || title === 'returns';
+    }
+
     function isProperty(title) {
@@ -92,6 +96,6 @@ return title === 'property' || title === 'prop';
     function isTypeParameterRequired(title) {
-        return isParamTitle(title) || title === 'define' || title === 'enum' ||
-            title === 'implements' || title === 'return' ||
-            title === 'this' || title === 'type' || title === 'typedef' ||
-            title === 'returns' || isProperty(title);
+        return isParamTitle(title) || isReturnTitle(title) ||
+            title === 'define' || title === 'enum' ||
+            title === 'implements' || title === 'this' ||
+            title === 'type' || title === 'typedef' || isProperty(title);
     }
@@ -164,3 +168,3 @@
 
-        return result;
+        return result.replace(/\s+$/, '');
     }
@@ -208,3 +212,2 @@
                 if (esutils.code.isLineTerminator(ch) && !(ch === 0x0D  /* '\r' */ && source.charCodeAt(last + 1) === 0x0A  /* '\n' */)) {
-                    lineNumber += 1;
                     waiting = true;
@@ -284,3 +287,3 @@ } else if (waiting) {
 
-        function scanIdentifier(last, allowPathChar) {
+        function scanIdentifier(last) {
             var identifier;
@@ -291,3 +294,3 @@ if (!esutils.code.isIdentifierStart(source.charCodeAt(index))) {
             identifier = advance();
-            while (index < last && isIdentifierPart(source.charCodeAt(index), allowPathChar)) {
+            while (index < last && esutils.code.isIdentifierPart(source.charCodeAt(index))) {
                 identifier += advance();
@@ -298,6 +301,2 @@ }
 
-        function isIdentifierPart(ch, allowPathChar) {
-            return esutils.code.isIdentifierPart(ch) || (allowPathChar && (ch === 45 || ch === 47));  // - and /
-        }
-
         function skipWhiteSpace(last) {
@@ -327,3 +326,3 @@ while (index < last && (esutils.code.isWhiteSpace(source.charCodeAt(index)) || esutils.code.isLineTerminator(source.charCodeAt(index)))) {
 
-            name += scanIdentifier(last, true);
+            name += scanIdentifier(last);
 
@@ -336,7 +335,13 @@ if (allowNestedParams) {
                     name += advance();
-                    name += scanIdentifier(last, true);
+                    name += scanIdentifier(last);
 
                 }
+                if(source.charCodeAt(index) === 0x5B  /* '[' */ && source.charCodeAt(index + 1) === 0x5D  /* ']' */){
+                    name += advance();
+                    name += advance();
+                }
                 while (source.charCodeAt(index) === 0x2E  /* '.' */ ||
+                        source.charCodeAt(index) === 0x2F  /* '/' */ ||
                         source.charCodeAt(index) === 0x23  /* '#' */ ||
+                        source.charCodeAt(index) === 0x2D  /* '-' */ ||
                         source.charCodeAt(index) === 0x7E  /* '~' */) {
@@ -352,3 +357,2 @@ name += advance();
                 if (source.charCodeAt(index) === 0x3D  /* '=' */) {
-
                     // consume the '='' symbol
@@ -359,11 +363,23 @@ name += advance();
                     var ch;
+                    var bracketDepth = 1;
                     // scan in the default value
                     while (index < last) {
                         ch = source.charCodeAt(index);
-                        if (ch === 0x5D   /* ']' */ || esutils.code.isWhiteSpace(ch)) {
+
+                        if (esutils.code.isWhiteSpace(ch)) {
+                            skipWhiteSpace(last);
+                            ch = source.charCodeAt(index);
+                        }
+
+                        if (ch === 0x5B /* '[' */) {
+                            bracketDepth++;
+                        } else if (ch === 0x5D  /* ']' */ &&
+                            --bracketDepth === 0) {
                             break;
                         }
+
                         name += advance();
                     }
                 }
+
                 skipWhiteSpace(last);
@@ -436,3 +452,3 @@
                     if (!this._tag.type) {
-                        if (!isParamTitle(this._title)) {
+                        if (!isParamTitle(this._title) && !isReturnTitle(this._title)) {
                             if (!this.addError('Missing or invalid tag type')) {
@@ -542,2 +558,18 @@ return false;
 
+        TagParser.prototype.parseCaption = function parseDescription() {
+            var description = trim(sliceSource(source, index, this._last));
+            var captionStartTag = '<caption>';
+            var captionEndTag = '</caption>';
+            var captionStart = description.indexOf(captionStartTag);
+            var captionEnd = description.indexOf(captionEndTag);
+            if (captionStart >= 0 && captionEnd >= 0) {
+                this._tag.caption = trim(description.substring(
+                    captionStart + captionStartTag.length, captionEnd));
+                this._tag.description = trim(description.substring(captionEnd + captionEndTag.length));
+            } else {
+                this._tag.description = description;
+            }
+            return true;
+        };
+
         TagParser.prototype.parseKind = function parseKind() {
@@ -580,2 +612,19 @@ var kind, kinds;
 
+        TagParser.prototype.parseThis = function parseAccess() {
+            // this name may be a name expression (e.g. {foo.bar})
+            // or a name path (e.g. foo.bar)
+            var value = trim(sliceSource(source, index, this._last));
+            if (value && value.charAt(0) === '{') {
+                var gotType = this.parseType();
+                if (gotType && this._tag.type.type === 'NameExpression') {
+                    this._tag.name = this._tag.type.name;
+                    return true;
+                } else {
+                    return this.addError('Invalid name for this');
+                }
+            } else {
+                return this.parseNamePath();
+            }
+        };
+
         TagParser.prototype.parseVariation = function parseVariation() {
@@ -611,3 +660,5 @@ var variation, text;
                 this._tag.type = this._extra.name;
-                this._tag.name = undefined;
+                if (!this._tag.name) {
+                    this._tag.name = undefined;
+                }
 
@@ -637,2 +688,4 @@ if (!sloppy) {
             'extends': ['parseType', 'parseNamePathOptional', 'ensureEnd'],
+            // http://usejsdoc.org/tags-example.html
+            'example': ['parseCaption'],
             // http://usejsdoc.org/tags-deprecated.html
@@ -685,3 +738,3 @@ 'deprecated': ['parseDescription'],
             // http://usejsdoc.org/tags-this.html
-            'this': ['parseNamePath', 'ensureEnd'],
+            'this': ['parseThis', 'ensureEnd'],
             // http://usejsdoc.org/tags-todo.html
@@ -724,4 +777,2 @@ 'todo': ['parseDescription'],
 
-            // Seek global index to end of this tag.
-            index = this._last;
             return this._tag;
@@ -731,3 +782,3 @@ };
         function parseTag(options) {
-            var title, parser;
+            var title, parser, tag;
 
@@ -744,3 +795,9 @@ // skip to tag
             parser = new TagParser(options, title);
-            return parser.parse();
+            tag = parser.parse();
+
+            // Seek global index to end of this tag.
+            while (index < parser._last) {
+                advance();
+            }
+            return tag;
         }
@@ -747,0 +804,0 @@

lib/typed.js

@@ -1003,3 +1003,3 @@ /*
 
-        elements = [ expr ];
+        elements = [expr];
         consume(Token.PIPE);
@@ -1006,0 +1006,0 @@ while (true) {

package.json

 {
   "name": "doctrine2",
   "description": "JSDoc parser",
-  "homepage": "http://github.com/Constellation/doctrine.html",
+  "homepage": "https://github.com/eslint/doctrine",
   "main": "lib/doctrine.js",
-  "version": "0.6.7",
+  "version": "1.2.2",
   "engines": {
@@ -22,5 +22,15 @@ "node": ">=0.10.0"
     {
+      "name": "Nicholas C. Zakas",
+      "email": "[e-mail]",
+      "web": "https://www.nczonline.net"
+    },
+    {
       "name": "Yusuke Suzuki",
       "email": "[e-mail]",
-      "web": "http://github.com/Constellation"
+      "web": "https://github.com/Constellation"
+    },
+    {
+      "name": "Chris",
+      "email": "[e-mail]",
+      "web": "https://github.com/chriswong"
     }
@@ -34,12 +44,12 @@ ],
     "coveralls": "^2.11.2",
-    "gulp": "^3.8.10",
-    "gulp-bump": "^0.1.13",
-    "gulp-eslint": "^0.5.0",
-    "gulp-filter": "^2.0.2",
-    "gulp-git": "^1.0.0",
-    "gulp-istanbul": "^0.6.0",
-    "gulp-jshint": "^1.9.0",
-    "gulp-mocha": "^2.0.0",
-    "gulp-tag-version": "^1.2.1",
-    "jshint-stylish": "^1.0.0",
+    "dateformat": "^1.0.11",
+    "eslint": "^1.10.3",
+    "eslint-release": "^0.3.0",
+    "istanbul": "^0.4.1",
+    "linefix": "^0.1.1",
+    "mocha": "^2.3.3",
+    "npm-license": "^0.3.1",
+    "semver": "^5.0.3",
+    "shelljs": "^0.5.3",
+    "shelljs-nodecli": "^0.1.1",
     "should": "^5.0.1"
@@ -50,15 +60,16 @@ },
       "type": "BSD",
-      "url": "http://github.com/Constellation/doctrine/raw/master/LICENSE.BSD"
+      "url": "http://github.com/eslint/doctrine/raw/master/LICENSE.BSD"
     }
   ],
   "scripts": {
-    "test": "gulp",
-    "unit-test": "gulp test",
-    "lint": "gulp lint",
-    "coveralls": "cat ./coverage/lcov.info | coveralls && rm -rf ./coverage"
+    "test": "npm run lint && node Makefile.js test",
+    "lint": "eslint lib/",
+    "release": "eslint-release",
+    "alpharelease": "eslint-prerelease alpha",
+    "betarelease": "eslint-prerelease beta"
   },
   "dependencies": {
     "esutils": "^1.1.6",
-    "isarray": "0.0.1"
+    "isarray": "^1.0.0"
   }
 }

README.md

@@ -1,28 +0,53 @@
-doctrine ([doctrine](http://github.com/Constellation/doctrine)) is JSDoc parser.
+[![NPM version][npm-image]][npm-url]
+[![build status][travis-image]][travis-url]
+[![Test coverage][coveralls-image]][coveralls-url]
+[![Downloads][downloads-image]][downloads-url]
+[![Join the chat at https://gitter.im/eslint/doctrine](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/eslint/doctrine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-[![Build Status](https://travis-ci.org/Constellation/doctrine.svg?branch=master)](https://travis-ci.org/Constellation/doctrine)
-[![Coverage Status](https://img.shields.io/coveralls/Constellation/doctrine.svg)](https://coveralls.io/r/Constellation/doctrine?branch=master)
-[![Dependency Status](https://david-dm.org/Constellation/doctrine.svg)](https://david-dm.org/Constellation/doctrine)
-[![devDependency Status](https://david-dm.org/Constellation/doctrine/dev-status.svg)](https://david-dm.org/Constellation/doctrine#info=devDependencies)
-[![Gitter chat](https://badges.gitter.im/Constellation/doctrine.png)](https://gitter.im/Constellation/doctrine)
+# Doctrine
 
-It is now used by content assist system of [Eclipse Orion](http://www.eclipse.org/orion/) ([detail](http://planetorion.org/news/2012/10/orion-1-0-release/)). And used as JSDoc validator in [ESLint](http://eslint.org/).
+Doctrine is a [JSDoc](http://usejsdoc.org) parser that parses documentation comments from JavaScript (you need to pass in the comment, not a whole JavaScript file).
 
-Doctrine can be used in a web browser with using browserify.
-or in a Node.js application via the package manager:
+## Installation
 
-    npm install doctrine
+You can install Doctrine using [npm](https://npmjs.com):
 
-simple example:
+```
+$ npm install doctrine --save-dev
+```
 
-    doctrine.parse(
-        [
-            "/**",
-            " * This function comment is parsed by doctrine",
-            " * @param {{ok:String}} userName",
-            "*/"
-        ].join('\n'), { unwrap: true });
+Doctrine can also be used in web browsers using [Browserify](http://browserify.org).
 
-and gets following information
+## Usage
 
+Require doctrine inside of your JavaScript:
+
+```js
+var doctrine = require("doctrine");
+```
+
+### parse()
+
+The primary method is `parse()`, which accepts two arguments: the JSDoc comment to parse and an optional options object. The available options are:
+
+* `unwrap` - set to `true` to delete the leading `/**`, any `*` that begins a line, and the trailing `*/` from the source text. Default: `false`.
+* `tags` - an array of tags to return. When specified, Doctrine returns only tags in this array. For example, if `tags` is `["param"]`, then only `@param` tags will be returned. Default: `null`.
+* `recoverable` - set to `true` to keep parsing even when syntax errors occur. Default: `false`.
+* `sloppy` - set to `true` to allow optional parameters to be specified in brackets (`@param {string} [foo]`). Default: `false`.
+* `lineNumbers` - set to `true` to add `lineNumber` to each node, specifying the line on which the node is found in the source. Default: `false`.
+
+Here's a simple example:
+
+```js
+var ast = doctrine.parse(
+    [
+        "/**",
+        " * This function comment is parsed by doctrine",
+        " * @param {{ok:String}} userName",
+        "*/"
+    ].join('\n'), { unwrap: true });
+```
+
+This example returns the following AST:
+
     {
@@ -52,63 +77,22 @@ "description": "This function comment is parsed by doctrine",
 
-see [demo page](http://constellation.github.com/doctrine/demo/index.html) more detail.
+See the [demo page](http://eslint.org/doctrine/demo/) more detail.
 
-### Options
+## Team
 
-#### doctrine.parse
-We can pass options to `doctrine.parse(comment, options)`.
-```js
-{
-    unwrap: boolean,          // default: false
-    tags: [ string ] | null,  // default: null
-    recoverable: boolean,     // default: false
-    sloppy: boolean,          // default: false
-    lineNumbers: boolean      // default: false
-}
-```
+These folks keep the project moving and are resources for help:
 
-##### unwrap
+* Nicholas C. Zakas ([@nzakas](https://github.com/nzakas)) - project lead
+* Yusuke Suzuki ([@constellation](https://github.com/constellation)) - reviewer
 
-When `unwrap` is `true`, doctrine attempt to unwrap comment specific string from a provided comment text. (removes `/**`, `*/` and `*`)
-For example, `unwrap` transforms
-```
-/**
- * @param use
- */
-```
-to
-```
-@param use
-```
-If a provided comment has these comment specific strings, you need to specify this `unwrap` option to `true`.
+## Contributing
 
-##### tags
+Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the [ESLint Contributor Guidelines](http://eslint.org/docs/developer-guide/contributing), so please be sure to read them before contributing. If you're not sure where to dig in, check out the [issues](https://github.com/eslint/doctrine/issues).
 
-When `tags` array is specified, doctrine only produce tags that is specified in this array.
-For example, if you specify `[ 'param' ]`, doctrine only produces `param` tags.
-If null is specified, doctrine produces all tags that doctrine can recognize.
+## Frequently Asked Questions
 
-##### recoverable
+### Can I pass a whole JavaScript file to Doctrine?
 
-When `recoverable` is `true`, doctrine becomes `recoverable` - When failing to parse jsdoc comment, doctrine recovers its state and attempt to continue parsing.
+No. Doctrine can only parse JSDoc comments, so you'll need to pass just the JSDoc comment to Doctrine in order to work.
 
-##### sloppy
 
-When `sloppy` is `true`,
-```
-@param String [foo]
-```
-'s `[foo]` is interpreted as a optional parameter, not interpreted as a name of this `@param`.
-
-##### lineNumbers
-
-When `lineNumbers` is `true`, parsed tags will include a `lineNumber` property indicating the line (relative to the start of the comment block) where each tag is located in the source. So, given the following comment:
-```
-/**
- * @param {String} foo
- * @return {number}
- */
-```
-The `@param` tag will have `lineNumber: 1`, and the `@return` tag will have `lineNumber: 2`.
-
-
 ### License
@@ -178,1 +162,15 @@
 http://www.apache.org/licenses/
+
+
+### Where to ask for help?
+
+Join our [Chatroom](https://gitter.im/eslint/doctrine)
+
+[npm-image]: https://img.shields.io/npm/v/doctrine.svg?style=flat-square
+[npm-url]: https://www.npmjs.com/package/doctrine
+[travis-image]: https://img.shields.io/travis/eslint/doctrine/master.svg?style=flat-square
+[travis-url]: https://travis-ci.org/eslint/doctrine
+[coveralls-image]: https://img.shields.io/coveralls/eslint/doctrine/master.svg?style=flat-square
+[coveralls-url]: https://coveralls.io/r/eslint/doctrine?branch=master
+[downloads-image]: http://img.shields.io/npm/dm/doctrine.svg?style=flat-square
+[downloads-url]: https://www.npmjs.com/package/doctrine

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

No website

Quality

Package does not have a website.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

95363

increased by5.6%

Number of package files

9

increased by12.5%

Lines of code

1915

increased by2.74%

Number of low quality alerts

0

decreased by-100%

Worsened metrics

Number of lines in readme file

175

decreased by-1.13%

Dependency changes

• + Addedisarray@1.0.0(transitive)

• - Removedisarray@0.0.1(transitive)

• Updatedisarray@^1.0.0