Nested object parameter descriptions are not included in the output

[xuhdev]

Search terms

nested object

Expected Behavior

Descriptions of nested object types should be generated in the output.

Actual Behavior

Descriptions of nested object types are not generated in the output.

Steps to reproduce the bug

1. Write the following file:

/**
 *
 * @param props - Component properties.
 * @param props.title - Title.
 * @param props.options - Options.
 * @param props.options.featureA - Turn on or off featureA.
 * @param props.options.featureB - Turn on or off featureB.
 */
function ComponentWithOptions({
  title,
  options,
}: {
  title: string;
  options: { featureA: boolean; featureB: boolean };
}) {}

2. Invoke typedoc on the file.
3. The output looks like the following:

Note the descriptions of featureA and featureB are completely missing.

Environment

• Typedoc version: 0.25.13
• TypeScript version: 5.4.5
• Node.js version: 20.12.2
• OS: Debian

[Gerrit0]

This is controlled by

typedoc/src/lib/converter/plugins/CommentPlugin.ts

Lines 644 to 648 in cf3dcd1

	// Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
	function moveNestedParamTags(
	/* in-out */ paramTags: CommentTag[],
	parameters: ParameterReflection[],
	) {

[pastelsky]

@Gerrit0 what is needed to be done here? I can try and give this a shot.

[Gerrit0]

The function that I linked to above is what's responsible for moving @param comments, it currently only does one level deep, so it needs to be updated to be recursive or some other way too handle dotted name paths that are more than one deep.

[Oblarg]

Sideways angle at this: if TypeDoc adds an @expand annotation, that could be used along with defining the type out-of-line to achieve effectively the same thing.

I feel like this feature could encourage poor practice - inline parameter typedefs can be bulky and hard to consume. When they start growing rich enough to need this, shouldn't you make the type explicit?