在前端开发中，我们经常会用到各种各样的 npm 包来完成我们的工作。而 tsdoc 是一种专门为 TypeScript 开发者设计的文档生成工具，可以帮助我们方便地为我们的 TypeScript 代码生成文档页面。下面将介绍如何使用 tsdoc。
安装
首先，我们需要安装 tsdoc。这可以通过使用 npm 来完成：
npm install -g @microsoft/tsdoc
使用
初始化
在使用 tsdoc 之前，我们需要先在项目中初始化配置文件。在项目根目录下执行以下命令：
npx tsdoc init
这将会在项目中生成一个名为 tsdoc.json 的配置文件。
为代码添加注释
一旦我们完成了配置，接下来就是为我们的代码添加注释了。tsdoc 使用一套特殊的注释语法来生成我们的文档页面。这个语法非常直观易懂，示例如下：
-- -------------------- ---- -------
---
- ------- -------- -------------
-
- -------------
- ----- ---------- - --- -----------
- ------------------------------------------ -- -- ------- -------
- ---
--
------ ----- -------- -
--- ---- --
------ -------- --------- -------
---
- ------ -------- ---
-
- ------ -------- - -----
--
--------------------- ------- -
------------- - ---------
-
---
- ------
-
- ------ ---- - -------
- -------- ----
--
------ -------------- -------- ------ -
------ ------------------ ----------
-
-在这个示例代码中，我们为 Greeting 类添加了注释。我们可以看到，这些注释针对不同的类成员给出了不同的说明，比如描述了该类的功能、该类的构造函数说明以及某个方法的说明等等。
生成文档
一旦我们添加了注释，我们就可以使用 tsdoc 来生成文档了。在终端中执行以下命令即可：
npx tsdoc
这将在项目中生成一个名为 docs/ 的文件夹，里面包含了我们生成的文档页面。
发布到 git pages
不少的异常重要代码都不是公开发布出去的，但作为一名程序员，我们经常会需要让别人接手我们的代码，这时候，文档显得格外的重要。我们将 tsdoc 生成的文档推送到 GitHub Pages 上是非常简单的，只需要执行以下命令即可：
npx gh-pages -d docs/
这个命令将会将我们的 docs/ 文件夹里的内容推送到 GitHub Pages 上，我们只需要访问我们的项目对应的页面，就能够方便地看到我们生成的文档页面。
总结
以上就是透过 tsdoc 帮助我们生成 TypeScript 代码文档的步骤。在开发 TypeScript 代码的时候，如果你能善用 tsdoc，那么你就可以方便地为你的代码生成易于阅读的文档页。这不仅可以帮助你自己更好地理解你的代码，也可以让你的团队以及社区中的其他开发者更好地理解你的代码，从而更好地使用和维护它们。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/59045