Support parsing inline tags (such as {@link Something})

[kraenhansen]

To support marking types referenced by inlined {@link ...} tags as used, we'd need to add parsing of inline tags to this package as per this comment:

@es-joy/jsdcomment is meant as a place for reusable utilities of interest to projects using JSDoc, but it should probably only add properties (e.g., an inlineTags array property with objects like {offset: [start: number, end: number], tag: string, text: string, path: string, linkStyle: "plain"|"markdown"|"pipe"|"space"}) since existing code depends on the current structure. (The linkStyle is following the four listed styles at both https://jsdoc.app/tags-inline-link.html and https://jsdoc.app/tags-inline-tutorial.html .) Another benefit of adding to jsdoccomment is we can build comment AST for it--so rules can target JSDoc blocks using specific inline tags or structures of inline tags.

[kraenhansen]

@brettz9 I started this issue to talk about it more specifically.

I would love to discuss the shape of the AST. More specifically, we would probably want to support two modes:

An inline tag in a plain description:

/**
 * Take a look at {@link Something}.
 */

An inline tag inside another tag's text (in this case @see):

/**
 * @see Take a look at {@link Something}.
 */

In the latter case think it would be valuable to to have the inlineTags on the AST node for the see node, instead of simply an array of inlineTags on the parser result directly. What do you think?

[brettz9]

Yes, fully agree. One challenge that just occurred to me—for either type—is how to express the offset. I think the offset should probably be relative to the description portion (i.e., @tag {type} [name] description or the block description /** description */), but there's also the issue of counting offsets when there are multiple lines in a description. I guess offsets would still work regardless of whether newlines were there or not.