Description
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.