如果你正在使用 AngularJS 进行开发，那么很有可能你需要记录下你的指令、控制器、服务等内容的文档，这样能够方便团队其他人员快速了解你的代码，也方便自己查阅已有的代码。
npm 包 gulp-ngdocs 就是为 AngularJS 应用程序生成文档的一种工具。它能够帮助你将你的 AngularJS 代码注释好，然后生成 HTML 文档，其中包括你的指令、控制器、服务等的文档和示例。
安装和配置 gulp-ngdocs
首先，你需要先安装 Node.js 和 npm 包管理器。之后，你可以使用以下命令安装 gulp-ngdocs：
npm install gulp-ngdocs --save-dev
然后，在你的 gulpfile.js 文件中添加以下代码：
-- -------------------- ---- -------
--- ---- - ----------------
--- ------ - -----------------------
----------------- --- -------- -- -
--- ------- - -
---------- ------
-------- -------------- ----------
---------- -------
--
------ -------------------------
------------------------------
---------------------------
---上述代码包含了一个名为 docs 的 gulp 任务，它会使用 gulp-ngdocs 生成你的 AngularJS 文档。在代码中，你需要指定 AngularJS 的核心脚本和你的应用程序脚本的路径，同时还需要指定生成文档的起始页面。
如果你正在使用 HTML5 模式，请将 html5Mode 设置为 true。
编写注释
你需要在你的 AngularJS 代码中编写注释，指示 gulp-ngdocs 什么应该被记录下来。以下是一个指令的例子：
-- -------------------- ---- -------
---
- ------ ---------
- ----- -----------
- --------- -
- ------------
- ---- -- -- ----------
-
- --------
- -------- ------------------
- ----- ------------------
- -----------------------------
- -------
- ----------
--
--------------------------------------------------- ---------- -
-- ---
---你需要使用 @ngdoc 和一些指令来标识你的指令、控制器等代码段。在上述代码中，@ngdoc directive 会告诉 gulp-ngdocs 这是一个指令。@name 指定了指令的名称，@restrict 指定了指令的限制类型。@description 是指令的说明。
在 @example 块中，你可以提供指令的示例代码。
生成文档
当你已经编写好注释后，你可以使用以下命令来生成文档：
gulp docs
你会在 docs 目录下找到生成的 HTML 文档。打开 index.html 文件，你会看到自动生成的文档。
在文档中，你可以看到你的 AngularJS 代码中被标记了的片段，同时也能够查看代码的示例和描述。
结论
使用 gulp-ngdocs 可以帮助你为你的 AngularJS 应用程序生成文档。这样，你的团队其他成员就能够更快地理解你的代码，同时也能够方便地了解如何使用你的指令、控制器等。
在编写注释时，你需要严格按照规范，使用 @ngdoc 和其它标记来标识你的代码。这样能够让 gulp-ngdocs 顺利地生成文档。
如果你正在使用 AngularJS 进行开发，那么应该尝试使用 gulp-ngdocs，因为这将给你的项目带来非常实际的好处。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedcaa5b5cbfe1ea0612475