Line break before @returns

[thernstig]

Motivation

Line breaks matters for readability, especially having a consistent line break style in documentation. I want to be able to enforce line breaks before @returns statements.

Current behavior

There is no configuration for it.

Desired behavior

I want this to be invalid:

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   * @returns {string} fooB - Some text
   */

I want this to be valid (with the new rule)

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   *
   * @returns {string} fooB - Some text
   */

Or for those who prefer, the other way around (the first example valid, the second invalid).

[brettz9]

This is already possible via the jsdoc/tag-lines rule. If you only want line breaks to apply for @returns, you could do something like this:

`jsdoc/tag-lines`: ['warn', 'any', {
  tags: {
    returns: {lines: 'always'}
  }
}]

Closing as that should resolve, but feel free to comment further as needed.

[thernstig]

@brettz9 that did unfortunately not work. It gave this:

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   * @returns {string} fooB - Some text
   *
   */

But I wanted this:

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   *
   * @returns {string} fooB - Some text
   */

I also tested with this config but that didn't work either:

    "jsdoc/tag-lines": [
      "warn",
      "any",
      {
        "noEndLines": true,
        "tags": {
          "returns": { "lines": "always" }
        }
      }
    ]

[brettz9]

Apologies about that.

The rule doesn't allow enforcing a specific number of lines before a given tag, but if @returns is your last item and you also want lines between @param, you could do this:

`jsdoc/tag-lines`: ['warn', 'always', {
  noEndLines": true
}]

However, if you don't want lines between @param, and just one empty line before @returns, then it seems like we need new configuration (though I don't think it would be trivial to add support for it given the current rule design).

[thernstig]

I want just one before @returns. So a new config option would be nice. Or alternatively that "noEndLines": true, actually means no end lines no matter the other config.

To me, this looks nicer:

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   * @param {string} fooB - Some text
   * @param {string} fooC - Some text
   *
   * @returns {string} fooD - Some text
   */

than this:

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   *
   * @param {string} fooB - Some text
   *
   * @param {string} fooC - Some text
   *
   * @returns {string} fooD - Some text
   */

or

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   * @param {string} fooB - Some text
   * @param {string} fooC - Some text
   * @returns {string} fooC - Some text
   */

[Ulrikop]

I stumbled across this issue and have to say: It would be great if I can configure jsdoc/tag-lines between tags of same group + between different groups.

The example of @thernstig is great but + blank lines between same tags of an other group like @example

  /**
   * Do something.
   *
   * @param {string} fooA - Some text
   * @param {string} fooB - Some text
   * @param {string} fooC - Some text
   *
   * @returns {string} fooD - Some text
   *
   * @example
   * ```
   * myFunction('a', 'b', 'c');
   * ```
   *
   * @example
   * ```
   * myFunction('z', 'y', 'z');
   *```
   */

I tried something like 'jsdoc/tag-lines': ['error', 'always', { tags: { param: { lines: 'never' } }, noEndLines: true }] but it didn't produce the expected behavior in all scenarios, so I had to disable the rule.

[thernstig]

@brettz9 Remove the questions label and add the feature label?

[jaydenseric]

I (and a lot of other people actually) have come to the conclusion that all formatting should be done by formatters (e.g. Prettier, Deno fmt), and not linters that visually report errors in the editor.

There are Prettier plugins for formatting JSDoc. If they are not to your taste they can be improved or alternatives can be published.

IMO eslint-plugin-jsdoc should remove all formatting related rules and stick to rules that relate to the semantics of JSDoc tags and content.

[thernstig]

@jaydenseric I can agree to that, yet that is a separate issue still. Until it is done, I would at least like this one to be solved.