I’m reading through a lot of code on CM6 and it seems that there are a lot of comments documenting what each type/function/field does, but it seems like they are sadly not compiled to the typescript definition files.
(Love the docs by the way, they’re all very well written and easy to understand!)
It would be nice if the comment style can be somehow converted to ts-doc so TypeScript can auto-include the comments. That way developers can see the documentation right out of their IDE.
Judging from the markdown syntax being used, I’m guessing some tool is generating the documentation site from these comments, so a migration may not be possible (or would be quite difficult).
Details/examples below.
Here’s an example:
Here’s what it compiles to in the .d.ts file, which is a shame since a lot of work has been put into the comments.
declare class Tag {
readonly set: Tag[];
static define(parent?: Tag): Tag;
static defineModifier(): (tag: Tag) => Tag;
}
I think if the comment syntax was switched to jsdoc (or ts-doc) style, TypeScript will automatically include them in the .d.ts definition file. This could then power the inline documentation that most IDEs support.
/**
* Comment
*/
Here’s an example of what I’m doing in my project that works well:
/**
* Renders markdown string to an HTML element.
* @param markdown - The markdown source code
* @param el - The element to append to
* @param sourcePath - The normalized path of this markdown file, used to resolve relative internal links
* @param component - A parent component to manage the lifecycle of the rendered child components, if any
*/
static renderMarkdown(markdown: string, el: HTMLElement, sourcePath: string, component: Component): Promise<void>;
That’s a good point about direct IDE support via comments in the .d.ts. There is some activity around adding support for triple-slash comments to TypeScript (#39930) and I’m kind of hoping that goes through at some point, since I much prefer this style of commenting. If that fails, we might at some point look into a custom tool that preprocesses the comments so that TypeScript preserves them.
That’s what I figured yeah… I also found a tsdoc issue in which one of the core typescript contributors wrote this, which I take to be the answer to the likelihood of this getting implemented.
I personally agree that /// is a better comment syntax than /**. If I were a benevolent dictator, I would deprecate /** and force everyone to adopt ///. But the JavaScript community has already mostly converged on /**. It seems unwise to go against that. And replacing one standard with “two standards” brings its own costs.
Of course you wrote these custom written tools to compile the comments to the documentation site, not surprised at all
I’ve personally used API extractor before which has the added benefit of rolling up the typescript definition files and generating the documentation site at the same time from the same source, but it’s also an imperfect solution with its own issues.
But the JavaScript community has already mostly converged on 