eslint / doctrine Goto Github PK
View Code? Open in Web Editor NEWJSDoc parser
License: Apache License 2.0
JSDoc parser
License: Apache License 2.0
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.
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
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").
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?
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?
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?
Supports and tests for @name
#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?
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
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.