Adequate our use of @link tag

[oandregal]

The spec defines block and inline tags. @block stand on their own, inline tags live within the description of block level tags and are wrapped by {}. Example:

@block-tag {type} A description with {@inline-tag} within it.

It looks like @link is an inline-only tag. Tools actually implement the @link as block and inline, so it's a non-issue at a practical level.

Action items

• Add a linting rule to prevent block-level use of the @link tag
• When the link tag is used as a block-level tag, we should substitute it by the @see tag instead. Fix: change block-level @link tag to @see tag #15616

Bad:

/**
 * Handles a delete keyDown event to handle merge or removal for collapsed
 * selection where caret is at directional edge: forward for a delete key,
 * reverse for a backspace key.
 *
 * @link https://en.wikipedia.org/wiki/Caret_navigation
 *
 * @param {KeyboardEvent} event Keydown event.
 */

Good:

/**
 * Handles a delete keyDown event to handle merge or removal for collapsed
 * selection where caret is at directional edge: forward for a delete key,
 * reverse for a backspace key.
 *
 * @see https://en.wikipedia.org/wiki/Caret_navigation
 *
 * @param {KeyboardEvent} event Keydown event.
 */

[oandregal]

Tagged as [Package] docgen just to have a way to group this somewhere. It doesn't actually affect anything docgen (other than being technically incorrect).

[gziolo]

@nosolosw can you add more details about what exactly needs to be done? :)

[oandregal]

Added more info in the description.

[aduth]

The action items could still be clearer, I think. Or at least, my initial impressions are, aside from just updating existing usage:

• Do we need to document this caveat somewhere?
• Can we enforce this (e.g. via linting), since it seems very easy to overlook? (speaking from experience ☺️ docgen: Omit docblocks with private tag #15173 )

[oandregal]

I don't know where this should be documented (if anywhere) but would love having a linting rule for it. Added the action item to the issue description.

[aduth]

To the point of the lint rule, #13741 is likely related here, as I expect the resolution there will migrate us toward eslint-plugin-jsdoc, which has an option to specify alias preferences.

https://www.npmjs.com/package/eslint-plugin-jsdoc#eslint-plugin-jsdoc-settings-alias-preference

{
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "link": "see"
            }
        }
    }
}

(It's not entirely clear to me whether tagNamePreference can be used for this tag specifically)

[codesue]

Hi, everyone! I'm a first time contributor here! May I work on the "update existing usage" portion of this fix? Should the changes be applied to all the relevant files that aren't listed in .gitignore or the files that are available before running ./bin/setup-local-env.sh? (I don't know if these are the same.)

[oandregal]

Hi, everyone! I'm a first time contributor here! May I work on the "update existing usage" portion of this fix?

👋 Suzen (@codesue), you're very welcome to do so! Ping me in the Pull Request you prepare for this and I'll make sure it gets reviewed.

As for the files involved: any JavaScript file that is not listed in .gitignore would be great.

[oandregal]

Noting that #15616 updated the @link tags that were meant to be @see ones.

[oandregal]

I'm triagging issues we don't plan to tackle. We can reopen if it regains interest.