jsdoc/check-line-alignment option to take into account existing alignment

[TheJaredWilcurt]

With my current settings, the linter wants to change my alignment from this

  /**
   * Description
   *
   * @param  {object} options  The user's options
   * @param  {string} message  The text to be logged
   * @param  {object} error    Optional object with additional details
   */

to this

  /**
   * Description
   *
   * @param {object} options The user's options
   * @param {string} message The text to be logged
   * @param {object} error   Optional object with additional details
   */

It should be able to detect that each section is starting at the same point on each line.

    'jsdoc/check-line-alignment': [
      1,
      'always',
      {
        'tags': [
          'param',
          'arg',
          'argument',
          'property',
          'prop',
          'returns',
          'return'
        ]
      }
    ],

• all lint settings

[brettz9]

@renatho : Just pinging you (given your related work) in case you might have the inclination to implement.

[renatho]

Hey there!

I wonder about a case like this, for example:

  /**
   * Description
   *
   * @param {object}  options  The user's options
   * @param  {string} message  The text to be logged
   * @param  {object} error    Optional object with additional details
   */

What would be the correct line? Maybe we could add a new option that would be the size of the spacings. If we set it to 2, it would consider this correct:

  /**
   * Description
   *
   * @param  {object}  options  The user's options
   * @param  {string}  message  The text to be logged
   * @param  {object}  error    Optional object with additional details
   */

Would it work for you @TheJaredWilcurt?

[brettz9]

Yeah, I went ahead and set the current tests to accept the lines at the beginning of the block as they are. Of course, if we implement the said feature, then indeed that sounds like a good solution to me (and also suggests the problematic line number if you were able to implement that also).

[TheJaredWilcurt]

I guess I should explain my reasoning for the spaces.

Between @param and {object} is 2, but if there was an @return it would be 1. Because the { starts at the same place either way.

  /**
   * Description
   *
   * @param  {object} error  Text
   */
  /**
   * Description
   *
   * @param  {object} name  Text
   * @return {obect}         Text
   */

It's just easier to copy/paste common @params around if they always line up, whether there's a @return or not. It's not uncommon to refactor and break code up into smaller methods where sometimes it needs a return and sometimes it doesn't.

I never put more than one space between } and the variable name, because the curly brace syntax visually separates the information well already. Unless the types vary in length, but the longest still only gets one space.

  /**
   * Description
   *
   * @param  {object} error  Text
   */
  /**
   * Description
   *
   * @param  {object}  name  Text
   * @param  {boolean} bool  Text
   */

I always use two spaces between the variable name and description, because it's just plain text and can visually get blurred with each other.

This is why I was requesting the rule just check to see if each section starts at the same point in the line. But I was just thinking of it from a detection standpoint. I think your proposal was from an auto-fix standpoint. So I don't think it would be worth it to try to have some magic logic around the "2 spaces after tag if no return, or 1 if there is". As long as the linter can auto-fix the spacing after the tag, I'd be fine with it just being set to a number. But could we get greater granularity, like a option like this:

{
  // @param {string}
  afterTag: 1
  // {string} name
  afterVariableType: 1
  // name  Text
  afterVariableName: 2
}

[brettz9]

Sure. And isn't it remarkable how much we all love our little jsdoc zen gardens enough to have these feelings of proportion and beauty about it? :-)

Thankfully with comment-parser's latest API, we can have such fine-grained control

As far as "2 spaces after tag if no return, or 1 if there is", this is actually not a problem for us because we already have a concept--not through comment-parser but through our use of code now extracted to @es-joy/jsdoccomment--of specifying which tags have names and which do not (including @param which does and @returns which does not).

I like your object proposal, though for simplicity (and consistency with comment-parser for that matter), I'd suggest the following (note, adding postDelimiter):

{
  postDelimiter: 1, // After the asterisk
  // @param {string}
  postTag: 1
  // {string} name
  postType: 1
  // name  Text
  postName: 2
}

[renatho]

Hey folks! I added a PR for that!
Please, let me know if it works for you. And I'd appreciate if you could help me testing if I didn't miss anything. =)

[gajus]

🎉 This issue has been resolved in version 34.7.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀