Derive parameter name of desctructured parameter from JSDoc comment

[Gudahtt]

Search Terms

__namedParameters, destructured parameter, @param

Problem

TypeDoc sets the name of any destructured parameters to "__namedParameters", even when a name is given in the JSDoc comment. This also results in the description of this parameter (and any child properties) in the JSDoc comment being ignored.

This relates to the "@param dot syntax" that is currently under consideration in TSDoc. TypeDoc already supports the dot syntax for parameters with names (i.e. when they are not being destructured), but it doesn't work for the more common scenario where the parameter is destructured inline.

For example, with this code snippet, all descriptions are rendered correctly:

/**
 * Concatenate strings 'a' and 'b'
 *
 * @param options - The options.
 * @param options.a - The 'a' string.
 * @param options.b - The 'b' string.
 */
function concatAB(options: { a: string, b: string }) {
  const { a, b } = options;
  return a + b;
}

But in this example, the @param tags end up being ignored because TypeDoc doesn't understand that the options param is the descructured parameter:

/**
 * Concatenate strings 'a' and 'b'
 *
 * @param options - The options.
 * @param options.a - The 'a' string.
 * @param options.b - The 'b' string.
 */
function concatAB({ a: string, b: string }) {
  return a + b;
}

Suggested Solution

We could set the name of the parameter to the name given in the JSDoc comment. This would also ensure the descriptions are correctly matched up. This relies upon the assumption that the JSDoc @param tags are present for all parameters, and that they are correctly ordered, so we can add a check to ensure this replacement only occurs if this appears to be the case (or maybe we can make this configurable?).

I am unaware of what other similar tools do in this circumstance.

I'd be happy to do this in a plugin instead, but I'm not sure that it would be possible. This relies upon the parsed comment, so it can't be triggered by the EVENT_CREATE_SIGNATURE, EVENT_CREATE_DECLARATION, or EVENT_CREATE_TYPE_PARAMETER event, because how would we be certain the comment was resolved by then? I think it would need to be done during the "resolve" phase, which is when the information in the parsed comment gets incorporated into the signature at the moment. So we could do this in a plugin that gets triggered by the beginning of the resolve phase, but that would be challenging without duplicating the functionality of addCommentToSignatures, or somehow guaranteeing that the plugin gets run before that function.

[Gudahtt]

I've created a draft PR to better explain how this could be done (#1704). It doesn't have tests yet, but it does pass all existing tests. If you think this is worth pursuing further, I can update the PR to include better test coverage. I would also be happy to help with documentation updates.

[Gerrit0]

I like this idea - it matches how VSCode recognizes comments, and is fairly intuitive to use.

[Gudahtt]

Great! I've just updated the PR with tests and marked it as ready for review.