eslint / doctrine

JSDoc parser

Doctrine

Doctrine is a JSDoc parser that parses documentation comments from JavaScript (you need to pass in the comment, not a whole JavaScript file).

Deprecation notice

This project is no longer maintained. See the ESLint website for more details.

Installation

You can install Doctrine using npm:

$ npm install doctrine --save-dev

Doctrine can also be used in web browsers using Browserify.

Usage

Require doctrine inside of your JavaScript:

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.
• range - set to true to add range to each node, specifying the start and end index of the node in the original comment. Default: false.

Here's a simple example:

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:

{
    "description": "This function comment is parsed by doctrine",
    "tags": [
        {
            "title": "param",
            "description": null,
            "type": {
                "type": "RecordType",
                "fields": [
                    {
                        "type": "FieldType",
                        "key": "ok",
                        "value": {
                            "type": "NameExpression",
                            "name": "String"
                        }
                    }
                ]
            },
            "name": "userName"
        }
    ]
}

See the demo page more detail.

Team

These folks keep the project moving and are resources for help:

• Nicholas C. Zakas (@nzakas) - project lead
• Yusuke Suzuki (@constellation) - reviewer

Contributing

Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the ESLint Contributor Guidelines, so please be sure to read them before contributing. If you're not sure where to dig in, check out the issues.

Frequently Asked Questions

Can I pass a whole JavaScript file to Doctrine?

No. Doctrine can only parse JSDoc comments, so you'll need to pass just the JSDoc comment to Doctrine in order to work.

License

doctrine

Copyright JS Foundation and other contributors, https://js.foundation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

esprima

some of functions is derived from esprima

Copyright (C) 2012, 2011 Ariya Hidayat (twitter: @ariyahidayat) and other contributors.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

closure-compiler

some of extensions is derived from closure-compiler

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/

Where to ask for help?

Join our Chatroom

doctrine's Issues

Support constructor

part of #5

Support global

#5

Parsing @type has optional literal is failed on demo

For example, @type {foo=} is failed on demo page.
However, @param {foo=} is success.

Is the behavior by spec?

lineNumbers doesn't provided in throws

doctrine.parse('@param ', {strict: true, lineNumbers: true})

throws

{ name: 'DoctrineError', message: 'Braces are not balanced' }

Can exceptions have location (at least line, but better column) of an error?

Support since and version

Write tests for @since and @version for #5

Lack of support for optional type and name for @const and @constant

JSDoc3 allows for the optional type and name to be supplied to @const and @constant: http://usejsdoc.org/tags-constant.html

Part of #5

Release new version of doctrine

ESLint is throwing errors on @constructor it seems the last release was 11 days ago and that tag was added 10 days ago. So it needs a new version of Doctrine with that tag supported. Thank you.

/*eslint valid-jsdoc:2*/

    /**
     * Responsible for launching Limit Order tickets in a dialog.
     *
     * @constructor
     * @extends caplin.trading.ticket.TicketLauncher
     */
    function MyCons(){
    "use strict";
    }

Declarative tag definition

Makes tag definition declarative

@param tag without type

We're using your excellent doctrine .js library for parsing some jsdoc. We've noticed that leaving out the type from a @param comment prevents it and the rest of the comment from being parsed. The Jsdoc notes http://usejsdoc.org/tags-param.html suggest that the type is optional so we're wondering if this is intentional or perhaps a bug?

Example:

/** Neither of the parameters below, or the returns comment tag, are parsed
 * @param firstparam
 * @param {String} secondparam
 * @return {Number}
 */

The Jsdoc pages also outline a syntax for identifying optional parameters (by surrounding with []) and specifying default values, e.g. @param {String} [optionalparam="defaultvalue"]. Just wondering if you have any plans to support these jsdoc features?

Support requires

#5

Is it possible to create custom tags?

I admit I have not tried this, but since documentation and jsdoc do not mention this, I thought I should ask.

I just want to define a custom @tag and get rest of the line from doctrine as string. I know the library does this with predefined tags, but is it exposed somehow to be extended?

Thanks

Support readonly

#5

Suggestions for a code analyzer to pair this with?

I'm looking to generate docs that are informed by both the comment tags and the code. Any suggestions on where to start?

Last tag always has \n in the description

Hi,

the unwrap: true option fails to strip the last new line before */, so an empty description on the last tag in the comment always becomes '/' (not sure why) and a non-empty description always has a newline at the end.

In my code, I have to do this to remove spaces/newlines from before the end of the comment, before passing the comment to doctrine.

 comment = comment.replace(/[\s\n]*\*\/[\s\n]*$/, '*/');

Thanks

decomposition of doctrine.js

Currently it's 1700 lines

I'm looking to possibly reuse this to generate docs for another OS library, however the size of doctrine.js is rather large.
Can it not be broken down, modularised etc to private functions?

Doctrine throws an error for {function}

Right now, Doctrine throws an error on this:

/**
 * @param {function} foo desc
 */

However, if you capitalize "function", then it's okay:

/**
 * @param {Function} foo desc
 */

This doesn't appear to be a problem with other types ("object" vs. "Object", "string" vs. "String").

Support default

#5

Support namespace

Support and tests for @namespace
#5

Support deprecated

Part of #5

Update synonym comment

As mentioned: c8492a7#commitcomment-5615868

Support mixes and mixin

Part of #5

Support inner

#5

Support for typed access tags

The Closure compiler added support a while ago for specifying access level and type in one tag, like:

/** @private {number} */

For an example, see the constructor of goog.ui.Select:
https://code.google.com/p/closure-library/source/browse/closure/goog/ui/select.js#65
This style is also used in many other places in the Closure library.

Would you be open to adding support for this feature?

Support JSDoc 3 optional param style

JSDoc 3 supports this syntax for specifying optional params:

/* 
 * @param {Object} [location] An object containing the error line and column
 */

Right now, Doctrine throws a syntax error when it encounters this pattern. More info: http://usejsdoc.org/tags-param.html

Parse a file instead of a string

Can we parse a file instead of a string, realtime?

Publish new version

Would you mind publishing a new version to npm? The changes so far have covered most of my use cases.

Support instance

#5

How to get "class" name

Hi, I just want to ask, how can i get class name... for example, I have file "events" with this:

/**
 * A base class for event objects, so that they can support preventDefault and
 * stopPropagation.
 *
 * @param {string} type Event Type.
 * @param {Object=} opt_target Reference to the object that is the target of
 *     this event. It has to implement the {@code EventTarget} interface
 *     declared at {@link http://developer.mozilla.org/en/DOM/EventTarget}.
 * @constructor
 */
goog.events.Event = function(type, opt_target) { 
  //...
}

It's nice to have json with informations from jsdoc, but is there any way to get "goog.events.Event" name?

Adding in nested properties for @param

As @nzakas pointed out in #32 the support for @param to have nested properties should be present for at least JSDoc 2.

https://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameters_With_Properties

Some multiline tags support please?

Is there possibility to add multiline parsing of some tags? Or just param tag?

Test case:

var jsdoc = ['/**', 'Info', '@param {', '  {status: ?boolean},', '  {hint: ?boolean}', '} [condition] some info about ', 'condition param', '@param {boolean} yes'].join('\n * ')+'\n */';
console.log(jsdoc);
require('doctrine').parse(jsdoc, {unwrap:true});

And no tags ;-(

/**
 * Info
 * @param {
 *   {status: ?boolean},
 *   {hint: ?boolean}
 * } [condition] some info about
 * condition param
 * @param {boolean} yes
 */
{ description: 'Info', tags: [] }

Problem is here: jscs-dev/node-jscs#245

Support module

Part of #5

Crash on empty @param tag

Somehow it fails on line 1761 https://github.com/Constellation/doctrine/blob/master/doctrine.js#L1761

Case:

// throws "Cannot read property 'name' of undefined"
doctrine.parse('/**\n * @param \n*/', { unwrap: true });
// same
doctrine.parse('@param ');

;-(

Support static

#5

Move from JSLint to ESLint

As discussed @Constellation I think it would be worthwhile changing from JSLint to ESLint once all the rules you were testing for are supported.

Namely I think the only JSLint check that isn't supported that was being used is: eslint/eslint#625

In regards to the other work, I have added in the library and made sufficient changes to pass the default checks.

Support method

Add in support for @member, @func and @function part of #5

Support inline tags

JSDoc has several inline tags that can appear as part of a description. For example: http://usejsdoc.org/tags-link.html

It would be good to represent this in some way in Doctrine, especially if they appear to be a syntax error, such as:

/**
 * Hello {@link world!
 */

@throws causes parsing error

This results in a parsing error:

/**
 * @throws if something goes wrong
 */

However, this works okay:

/**
 * @throws {Error} if something goes wrong
 */

According to JSDoc, either is acceptable:
http://usejsdoc.org/tags-throws.html

Nested name value support for @prop and @property

I just noticed that the following isn't supported:

/**
 * @property {string} name.thing - desc
 */

Doc:
http://usejsdoc.org/tags-property.html

In the example above the '.thing' becomes part of the description.

Rename sloppy to jsdoc3

Basically doctrine supports Closure compiler tags.
But jsdoc3 tags are useful, so we need to support it.

Currently jsdoc3 style optional param is supported when sloppy flag is on. This is not suitable name. We should rename sloppy to something like jsdoc3.

Support name

Supports and tests for @name #5

Support private, protected, public

"Strict" parsing mode?

For ESLint, I really want to know when there's a syntax error in a JSDoc comment (JSDoc will usually error out). Right now, Doctrine silently ignores most errors and continues on to parse the rest. Is it possible to have a mode that throws errors when they occur rather than continuing on? Some examples I'd like to be able to catch:

// double @
/**
 * Description
 * @@param {string} name Param description
 */

// missing closing curly brace
/**
 * Description
 * @param {string name Param description
 * @param {int} foo Bar
 */

Support member and var

Support and tests for @member and @var. #5

Lack of name for @augments and @alias

I'm not sure if name is the right property name however @augments and @alias however the values supplied for the augmented name and alias name are filtered into the description property.

Missing @param type results in incorrect reporting of param name

If I have a JSDoc comment like this:

/**
 * My desc
 * @param foo Something descriptive
 */

The resulting node is:

{
    "description": "My description",
    "tags": [
        {
            "title": "param",
            "description": "descriptive",
            "type": {
                "type": "NameExpression",
                "name": "foo"
            },
            "name": "Something"
        }
    ]
}

I would have expected it to say that there is no type and that the name is "foo" rather than "something".

According to the JSDoc documentation (http://usejsdoc.org/tags-param.html), when there are no braces, the first identifier should be the parameter name and the rest should be the description.

Wrong detected tags in description

/**
 * Prevents the default action. It is equivalent to
 * {@code e.preventDefault()}, but can be used as the callback argument of
 * {@link goog.events.listen} without declaring another function.
 * @param {!goog.events.Event} e An event.
 */
goog.events.Event.preventDefault = function(e) {
  e.preventDefault();
};

is evaluated as:

{
    "description": "/**\nPrevents the default action. It is equivalent to\n{",
    "tags": [
        {
            "title": "code",
            "description": "e.preventDefault()}, but can be used as the callback argument of\n{@link goog.events.listen} without declaring another function."
        },
        {
            "title": "param",
            "description": "An event.\n/\ngoog.events.Event.preventDefault = function(e) {\ne.preventDefault();\n};",
            "type": {
                "type": "NonNullableType",
                "expression": {
                    "type": "NameExpression",
                    "name": "goog.events.Event"
                },
                "prefix": true
            },
            "name": "e"
        }
    ]
}

First three lines should be considered as description

Support JSDoc 3 tags

http://usejsdoc.org/index.html#JSDoc3_Tag_Dictionary

Augments causes a parse issue

When using @Augments tag a validation issue is thrown as {typename} is expected:
"Missing or invalid tag type"

http://usejsdoc.org/tags-augments.html - doesn't seem to suggest type should ever be used.

Lack of support for @extends

@extends isn't getting parsed at all at the moment due to a type restriction.

Part of #5

Document options

It looks like the parse() method accepts an options object as a second argument, but it's hard to tell what the possible options are from looking at the source code. Can you add some documentation for this?