Tsdoc: VS Code extension for TSDoc

[maasha]

e.g.

interface SquareConfig {
    color?: string;
    width?: number;
}

[octogonz]

Something like this:

/**
 * Describes a JavaScript object that specifies the configuration of a square.
 * @remarks
 * Use this interface with the {@link Renderer.drawShape} method.
 * @public
 */
interface SquareConfig {
    /**
     * An HTML color code such as `#00000` for black, etc.
     */
    color?: string;
    /**
     * The width of the square, measured in pixels.
     * If the width is omitted, then by default the square will be sized to fill its container.
     */
    width?: number;
}

@maasha Is that what you were looking for?

[maasha]

That is pretty standard, but I was wondering if alternatively one could use an @attr tag which could be used to briefly describe the attributes of the interface:

/**
 * Describes a JavaScript object that specifies the configuration of a square.
 * @attr color An HTML color code such as `#00000` for black, etc.
 * @attr width The width of the square, measured in pixels.
 * @remarks
 * Use this interface with the {@link Renderer.drawShape} method.
 * @public
 */
interface SquareConfig {
    color?: string;
    width?: number;
}

This would show up nicely on hover vscode (and Atom and others) for a quick overview of the interface:

[octogonz]

As far as TSDoc goes, I think we would prefer to fix VS Code so that it properly displays the documentation for the interface members. Whereas if we were to add an alternative syntax that is functionally equivalent to the main syntax, this would make the standard harder to learn and harder for implementors to parse.

Btw in your screenshot I don't think VS Code is actually understanding the @attr tag - it merely shows the comment content verbatim.

[maasha]

Right, I did notice that vscode renders any tag the same - and that is actually what made me wonder in the first place. I can agree to stick to the "main syntax" and then we wait for vscode team to improve the interface information displayed on hover? Will they do this?

[octogonz]

We might start by making a TSDoc extension for VS Code (similar to the recently released plugin for ESLint). This approach would also allow us to render the docs more nicely similar to what the playground does.

Before I would work on that myself, I have some higher priorities I've been wanting to wrap up, such as finishing the declaration reference parser and posting a spec that documents the TSDoc grammar in detail.

[maasha]

Awesome, let me know if you need testers