@param names are not rendered

[mk010101]

Search terms

@param hyphen

Expected Behavior

The name of the param should be visible next to the 'param' field. The @param block is followed by a parameter name and then a hyphen.

Actual Behavior

The generated document omits the actual param names and just lists the description.

Steps to reproduce the bug

/**
 * @param side1 - First (face) side
 * @param side2 - Second side
 * @param dir - Direction of rotation. @default 'true'
 */
interface FlipOptions  {
    side1: HTMLElement;
    side2: HTMLElement;
    dir?: -1 | 1;
    singleDir?: boolean;
    vertical?: boolean;
    lockPointer?: boolean;
}

Environment

• Typedoc version: 0.20.0-beta.24
• TypeScript version: 4.1.2
• Node.js version: 12.7.0
• OS: OSX

[Gerrit0]

This is due to the template partial for comment tags - it you to use @param tags for what they are meant to be used for, not for documenting properties. I'd accept a PR that rendered the name if present

https://github.com/TypeStrong/typedoc-default-themes/blob/7754c7df1d9280da3e90e4b500737484f979245f/src/default/partials/comment.hbs#L14-L17

[mk010101]

This is the output of the same from https://microsoft.github.io/tsdoc

As you can see, it works correctly.

[Gerrit0]

TSDoc != TypeDoc. TypeDoc doesn't currently conform to the TSDoc standard, though support for it is planned.

That demo is particularly misleading because it doesn't parse the source code - it only grabs a comment and then renders it. I suspect that if you ran that code through api-extractor, it would complain about your use of @param

[justinwilaby]

This defect also applies to the TypeScript binding syntax for member functions:

class MyClass {
/**
* Function that does stuff
* 
* @param param1 - The first param
* @param param2 - The second param
*/
protected boundFunction = (param1: string, param2: number): void {}

Is there another way to document this syntax?

[Gerrit0]

I'm not sure what you mean there. This seems to work as expected.

If you aren't seeing this, please open a new issue.

[cefn]

I encounter what I think is the same problem in the context of a function type definition.

/**
 * @param a The first number
 * @param b The second number
 */
export type MyFun = (a: number, b: number) => void;

...gets rendered like...

Note the elements inlined in the comment which are marked param and have lost the a and b names.

I am invoking the build command with no arguments...

npx typedoc --watch --out docs ./src/index.ts 

[Gerrit0]

That's a different bug - #799.

[cefn]

Thanks for your attention @Gerrit0 I've subscribed to that one.

[Gerrit0]

v0.22.x, I'm not too happy with this... but if you are seeing param tags rendered, you are likely using them in an unsupported way in the first place, so will leave it at this.