[Multiline block] Enforce text on zero and last lines

[SrBrahma]

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.

[brettz9]

But the rule should allow for empty descriptions if no next is following, e.g., if there is only a tag?

[SrBrahma]

Hi @brettz9, thanks for the quick reply!

Like

/**
 * @param foo
 * @param bar
 */

?

I globally searched now in some of my projects and haven't seen any multiline having a tag on the zeroth line, like

/** @param foo
 * @param bar */

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]

Yes I meant cases like you mention or just:

/**
  * @param foo
  */

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.

[SrBrahma]

Yes, those seem cases that can be handled by other rules.

[brettz9]

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]

🎉 This issue has been resolved in version 39.6.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀