Closed
Description
Motivation
I have a different taste for JSDoc. Never saw anyone doing it but for me it just looks way better by not having an entire line wasted just for the opener / closer.
Example:
/** A function that should create your user entry.
*
* Resolve it when the function call is concluded.
*
* Throwing will call signOut. */
createUserDbEntry: (params: CreateUserDbEntry) => Promise<any>;
is WAY better (at least for me) than
/**
* A function that should create your user entry.
*
* Resolve it when the function call is concluded.
*
* Throwing will call signOut.
*/
createUserDbEntry: (params: CreateUserDbEntry) => Promise<any>;
Current behavior
multiline-blocks
options allow them, but do no enforce them. Everyday I have to manually fix my JSDocs to fit my taste.
Desired behavior
multiline-blocks
options to enforce that /**
is proceeded and */
is be preceded with text. They will remove newlines and stars between them and any text.
Alternatives considered
Change my taste. But NO! Lines are too important to be wasted with just two or three meta characters.
Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.
Activity
brettz9 commentedon Jan 14, 2022
But the rule should allow for empty descriptions if no next is following, e.g., if there is only a tag?
ftzi commentedon Jan 14, 2022
Hi @brettz9, thanks for the quick reply!
Like
?
I globally searched now in some of my projects and haven't seen any multiline having a tag on the zeroth line, like
It looks awful to me this misalignment, I wouldn't do this at all. You did a nice observation. For texts, it just seems like an ok paragraph, better than wasting an entire line to the opener. The only cases I have a tag on the zeroth line is when it's a single line JSDoc, for @default. Seems that when I have a tag on multilines, I always start with a description text.
Personally, this case is for me a don't care situation as I never did it and certainly never will.
I don't have experience writing ESLint rules, but regarding this, maybe the easiest solution should be done.
brettz9 commentedon Jan 14, 2022
Yes I meant cases like you mention or just:
or:
I think this shouldn't report anything, as someone wanting to disallow can just use
jsdoc/require-description
for that. I.e., this should only report and fix if non-tag text is found on the next available line.ftzi commentedon Jan 14, 2022
Yes, those seem cases that can be handled by other rules.
fix(`no-restricted-syntax`): update jsdoccomment to be able to use ne…
brettz9 commentedon Nov 2, 2022
You should now be able to use
jsdoc/no-restricted-syntax
to get reports if the descriptive text does not begin on the 0th line or end with a new line: d68d742#diff-545a867764ce23fa04a08e7f0207aacd009b8343965ede162d8f09d9b718a844 . Note that there is no fixer, e.g., to collapse any newlines added by the user. But hopefully this should meet your use case. Feel free to comment further if you see any issues targeting the new properties illustrated in the examples.gajus commentedon Nov 2, 2022
🎉 This issue has been resolved in version 39.6.1 🎉
The release is available on:
Your semantic-release bot 📦🚀
Update dependency eslint-plugin-jsdoc to v39.6.2 (#1625)