eslint / doctrine Goto Github PK

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.

#5

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

#5

#5

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").

#5

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

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?

#5

Support and tests for @namespace
#5

Part of #5

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.

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
 */

Part of #5

Part of #5

As mentioned: c8492a7#commitcomment-5615868

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?

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?

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.

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

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.

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

Is the behavior by spec?

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

part of #5

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?

#5

Supports and tests for @name #5

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

/**
 * 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

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

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

Part of #5

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

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";
    }

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

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

Part of #5

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?

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.

Write tests for @since and @version for #5

#5

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

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 ');

;-(

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!
 */

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?

Makes tag definition declarative

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.

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

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

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