前言
在前端开发中，文档是非常重要的一个环节，它不仅可以让开发者更好地了解代码，同时也方便了与其他开发者共同协作。在 AngularJS 开发中，有一款非常优秀的文档生成工具 ngdocs。在 ngdocs 的基础上，yx-ngdocs 在生成文档的同时还增加了类似于 UI 组件的展示功能，提高了对 API 的可视化效果，让开发者更加直观地了解 API 使用方式。
安装
首先，我们需要安装 yx-ngdocs 依赖的一些包，包括：gulp、gulp-ngdocs、gulp-webserver、gulp-open、child_process 和 gulp-rename。可通过如下命令完成：
npm install gulp gulp-ngdocs gulp-webserver gulp-open child_process gulp-rename --save-dev
使用
案例介绍
我们使用代码编辑器创建一个 helloWorld.js 文件，并输入如下代码：
/**
* 输出 hello world
*/
function helloWorld() {
console.log('hello world');
}在 helloWorld.js 同级目录下创建一个 docs 文件夹，用于放置我们生成的文档文件。
yx-ngdocs 配置
在项目根目录下创建一个 gulpfile.js 文件（也可以在项目的 package.json 中增加一个 scripts 配置），并输入如下代码：
-- -------------------- ---- -------
----- ---- - ----------------
----- ------ - -----------------------
----- --------- - --------------------------
----- ---- - ---------------------
----- - --------- - - -------------------------
----- ------ - -----------------------
---
- -- --------- --
--
------------------------- -------- -- -
---------------- ----------- ------------- - ------ --------- --
---
---
- ------
--
----------------- --------------------------- -------- -- -
------ -------------------------
-----------------------
--------------------------
----
---
- -------------------
--
---------------------- -------- -- -
------ ------------------
-----------------
----------- -----
----- -----
----
---
------------------------ -------- -- -
------ ----------------------------------------- ---- -------- ----
---
---
- -------------
--
----------------------- -------- -- -
--------------------------- ---------------------
---
---
- -------
--
------------------------ -------- -- -
------ -----------------------------
-------------------------------------
---------------------------
---
--------------------
------------
--------------------- ------------ --------------
--------------
-------------
-
--以上代码会完成以下操作：
- 安装 yx-ngdocs 的依赖；
- 生成名为 helloWorld.js 的 API 文档到项目根目录下的 docs 目录中；
- 启动一个静态服务器，并使用 Chrome 浏览器自动打开文档页面；
- 监听 helloWorld.js 文件的变化，自动重新生成 API 文档；
- 将 API 文档文件的文件名修改为 helloWorld-docs.html，并将其保存在 docs 目录中。
生成文档
在终端中运行以下命令即可生成文档：
gulp
这里我们使用了 default 任务，它依赖于 docs，webserver，watch:docs，rename:docs 和 openbrowser 这几个任务，可以通过命令行执行 gulp flash 单独执行某个任务。
示例代码
我们在 helloWorld.js 中添加一些示例代码：
-- -------------------- ---- ------- --- - -- ----- ----- - - --- - - ------------- -- -- ------ ------ -- -------- ------------ - ------------------ -------- -
然后生成文档，即可看到示例代码效果：
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055fc681e8991b448dd384