I use ESDoc to generate a documentation for a JS project. It works well!
I now want to migrate this JS project into a TS project. For the documentation, I saw this plugin to help ESDoc handle TypeScript.
It kinds of work. By simply using the plugin, the doc is generated like before, as seen below:
/**
* @desc Stringify a number
* @param {number} nbr Number to stringify.
* @return {string} The stringified number.
* @example const str = stringify(42);
*/
stringify(nbr: number): string {
return `${nbr}`;
}
I find it's a bit awkward to define the types with TypeScript and inside the comment block. So, like the documentation says, I've removed these types from the comments:
/**
* @desc Stringify a number
* @param nbr Number to stringify.
* @return The stringified number.
* @example const str = stringify(42);
*/
stringify(nbr: number): string {
return `${nbr}`;
}
But because of that, the generated documentation has lost the types. TypeScript's types are not taken into account:
Funny thing, if I remove the tag @desc (and just the tag, not the corresponding text) like below, the results are also different:
/**
* Stringify a number
* @param nbr Number to stringify.
* @return The stringified number.
* @example const str = stringify(42);
*/
stringify(nbr: number): string {
return `${nbr}`;
}
This time, TypeScript's types are taken into account, but I've lost @param and @return descriptions and even the @example!
I must say I'm running out of ideas...
Do you know how can I take advantages of TypesScript's types without losing the rest of the documentation?
According to the documentation of esdoc-typescript-plugin, it's possible, but I can't manage to do that.
What am I doing wrong? :)
Thanks in advance!
