tspoff/token-playground

Add Code Comments and Code Documentation Project-Wide

Opened this issue · 2 comments

jordanmack commented

Add code comments and code documentation project-wide. Using a documentation tool like TSDoc or TypeDoc is recommended. We will find a place to publish the code documentation at a later time (probably GitHub pages).

tspoff commented

Do you have a recommendation on which tool to use? I haven't used either in the past. The microsoft standard shown w/ TSDoc seems like a good approach, so I'll probably go with that unless you think there's a better way.

jordanmack commented

In the past, I've used stuff like JSDoc, but I can't recommend that for TypeScript. Different solutions need to be investigated, and we should try to encourage all Nervos developers to follow the same recommendation.

The ideal solution:

  • Works with TypeScript.
  • Works with plain Javascript.
  • Is supported with autocomplete by popular editors like VSCode.
  • Can export to a browsable web page.
  • Has strong backing so it continues to be maintained.

TSDoc is probably the best bet, but alternatives should be looked at to be sure.