Closed GNRSN closed 1 year ago
According to the official site,
Block tags always begin with an at sign (@). Each block tag must be followed by a line break, with the exception of the last block tag in a JSDoc comment.
Besides this, our comment block parser, comment-parser
, and much of our code, expects a newline as well.
It does seem that your single line of code will get successfully tokenized as separate block tags at https://tsdoc.org/play/ , so it would seem that the TypeScript flavor of JSDoc may indeed allow for such placement, but as suggested, this would require us to use a new parser and make many changes which I'm regrettably not inclined to do.
I guess we could add an option to empty-tags
to ignore certain tags, e.g., if you always have @private
first, but it would mean not catching when @private
was not empty in some other context (and it still wouldn't check a tag in the position of @type
in your example (e.g., @const
) at all). Your best bet may unfortunately be continuing the disable the rule (assuming your tooling doesn't have a problem with the single line).
@brettz9 Thank you for the quick response!
We were tricked into believing this was valid jsdoc by TSC being too forgiving then 😉
With the arguments you present I understand why this would be an unreasonable change at the current time. Feel free to close this issue at your discretion.
With TypeScript kind of overtaking the standard and forming their own (with tsdoc), ideally we might have followed that, but yeah, not really inclined to attempt such a large overhaul at this point. Thanks for the report!
Motivation
Context:
We're mainly using JSdoc for typechecking with tsc, we're using
eslint-plugin-jsdoc
to enforce valid jsdoc but we have allrequire-
rules disabled as documentation is optionalExample:
We often find ourselves defining class properties as follows (simplified example)
constructor (options) {
...
/** @private @type {string} */
this._id = options.id
...
}
Current behavior
The aforementioned example triggers
empty-tags
with "@private should be empty", to satisfy the rule we have to update the example to:constructor (options) {
...
/**
* @private
* @type {string}
*/
this._id = options.id
...
}
Which becomes bloated for 5-10+ inline definitions
Desired behavior
Don't trigger
empty tags
when the following content is another tag, possibly only in the context of a single line commentAlternatives considered
Updating our codebase to multi-line comments (4 lines instead of 1) was rejected by the team, we've decided to disable the rule for now