Nested parameter descriptions

[jonchardy]

TypeDoc doesn't seem to have a way to provide comments for nested parameters. Consider the following TypeScript method:

/**
 * Test method with object param
 * @param {Object} options
 */
public foo(options: { first: string, second: number, third: (a: number) => number }) {

}

TypeDoc generates something like this:

Ideally there would be a way to provide descriptions for all parts of the parameter (first, second, third, a, returned number) using some sort of syntax within the comment. As it stands, I suppose it's possible to provide some sort of long description for the options param which describes each component of it, but then it becomes messy having the descriptions separated from the type information.

[aciccarello]

@jonchardy The best way to document a parameter object like that would be to define an interface. That also allows you to to reuse the interface. Is there a particular reason why you wouldn't define the interface externally?

[jonchardy]

Yea, that's probably a better option. Definitely more TypeScript-y.

[aciccarello]

@jonchardy I was just looking at one of the tests and it appears that you may be able document these as well.

/**
 * Test method with object param
 * @param options Describing the options param
 * @param options.first A description of the first property of the options param
 */
public foo(options: { first: string, second: number, third: (a: number) => number }) {

}

This matches how JSDoc handles @param. It should be added to the TypeDoc docs.

[StephanBijzitter]

I'm a bit confused.

This issue is closed, but it's in a project with status "to do" and what I get today is even less than the screenshot in the opening post.
All I see is options: object.

What do I do?

[Gerrit0]

The project it is in is documentation - we need to create clearer documentation on how this feature works.

The options: object is another bug - #1103 provides a partial fix that has one fatal flaw, and it will be fixed with #801.

[StephanBijzitter]

Ah, thanks! With the information in those issues I got it working indeed :-)
Not perfect, but I'm happy.