Skip to content

[Multiline block] Enforce text on zero and last lines #830

Closed
@ftzi

Description

@ftzi

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

brettz9 commented on Jan 14, 2022

@brettz9
Collaborator

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

ftzi

ftzi commented on Jan 14, 2022

@ftzi
Author

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

brettz9 commented on Jan 14, 2022

@brettz9
Collaborator

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.

ftzi

ftzi commented on Jan 14, 2022

@ftzi
Author

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

added a commit that references this issue on Nov 2, 2022
d68d742
brettz9

brettz9 commented on Nov 2, 2022

@brettz9
Collaborator

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

gajus commented on Nov 2, 2022

@gajus
Owner

🎉 This issue has been resolved in version 39.6.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @brettz9@gajus@ftzi

        Issue actions

          [Multiline block] Enforce text on zero and last lines · Issue #830 · gajus/eslint-plugin-jsdoc