Add callback tag, with type parameters

[sandersn]

1. Add the @callback tag.
2. Makes @template-declared type parameters work correctly with @callback and @typedef.
3. Parse and display comments on @callback and @typedef tags, not just their properties/parameters. Previously these were ignored.

/**
 * @callback Cb
 * @param {string} s
 * @return {number}
 */
/**
 * @template T
 * @typedef {Object} Counter
 * @property {number} n
 * @property {T} t
 */

The callback tag matches its parameters in order. The return tag must come last. Parameter names are not required to match:

/**
 * @callback Cb
 * @param {string} s
 */
/** @type {Cb} */
const f = ignored => { return; };

Note that a callback tag with a @template type parameter "uses up" that type parameter, even if the jsdoc comment is on a class or function. This only applies within a single comment, so you can get around this by using two comments:

/**
 * @template T
 * @callback Miracle
 * @return T
 */
/** @template T */
class C {
    /** @param {T} x */
    constructor(x) {
        /** @type {Miracle<T>} */ // This is the T from C<T>
        this.make = () => x
    }
}

Limitations:

1. Templates still don't support declaring constraints on their type variables.
2. There's no way to declare a construct signature.
3. There's no way to declare an object with a call signature and properties using only the
4. Nested object literal syntax doesn't work correctly. This:

/**
 * @callback {Wat}
 * @param {Object} o
 * @param {number} o.nested
 * @param {string} s
 */

is equivalent to
type Wat = (o: { nested: number, s: string }) => void not
type Wat = (o: { nested: number }, s: string) => void as it should be.

1,2 and 3 are limitations of JSDoc syntax that would require us to innovate with no real benefit. 4 might work in other jsdoc parsers, but I don't think it's that important a scenario; people who want to use @callback instead of Typescript syntax are likely to want to create a separate type alias for every type.

Fixes #23740
Fixes #23745
Fixes #7515

Edit: Now also fixes
#17339

By improving the scoping of @template tags, which was previously too wide.

[weswigham]

Reminder: Some code introduced in #24153 should be changed before this is merged (to look up proper type params like this pr changes, and to support @callback like this pr supports), so quick info for callback tags is printed correctly. The TODO in the test in that PR should be removable once fixed.

[sandersn]

OK, the TODO is done. @weswigham

[weswigham]

😄

[weswigham]

Did this need to get reordered in the input file?

[sandersn]

I reordered it in the input file to show that @template works before or after. I was talking about it with @mhegazy and found that we had completely opposite intuitions about whether the usual order is before or after.

[weswigham]

This name should contain TypeArguments and not TypeParameters.

[sandersn]

I think there is an overall confusion in naming between typeArguments and typeParameters, because this function delegates to getLocalTypeParametersOfClassOrInstanceOfTypeAlias, which delegates to getEffectiveTypeParameterDeclarations. But then the result of this function is always assigned to aliasTypeArguments.

Ah, well, a big, complicated change is not the place to drop in another renaming.

[weswigham]

Type arguments is already definitely correct here - aliasTypeArguments always hold the interstated type arguments.

[weswigham]

I just a some small comment about a name, but it looks decent. I do worry about how well we'll handle JSDocSignatures, though, given they don't conform to the same SignatureDeclarationBase (I'd almost rather you change SignatureDeclarationBase to accommodate JSDocSignature as a SignatureDeclaration); but w/e.

[sandersn]

Yeah, I tried a couple of times to change SignatureDeclarationBase, but JSDocSignature was too different in shape and resulted in lots of special-case code throughout. I think this solution is slightly better.

[TheLarkInn]

This will land likely tonight I assume?

[mhegazy]

This will land likely tonight I assume?

yes