利用jsdoc为vue项目生成漂亮的文档

JavaScript012

利用jsdoc为vue项目生成漂亮的文档,第1张

jsdoc是前端自动生成文档所常用的工具。我们只要按照jsdoc的语法来书写注释就能顺利的生成一片很漂亮的文档。

只是jsdoc针对的是 js 文件,对于 .vue 文件似乎就有些无能为力了。不过既然 vue 这么人气,相信一定也会有相应的工具。在找了一圈之后,果然找到了一位前辈写的 jsdoc-vue 。

在研究了一下之后,发现这个工具主要解决了jsdoc不认 .vue 文件的问题。虽然可以让 .vue 文件自动生成文档,但生成出的文档样式却并不好看。于是就fork过来改造了一下。

废话不多说,先上一张生成的文档截图。

github地址: jsdoc-vue 改造版

这个改造后的版本我自己用着还算比较满意,比较重要的如 props 和 components 组件都可以利用jsdoc自带的语法比较清楚的表示出来。

如果各位喜欢的话,希望可以点一个star。当然,如果有改进的地方也希望各位可以指点一下。

YUIDoc 是一个基于 Node.js 的应用程序。新建个文档写着javascript写入过程并保存操作如下:

(1)YUIDoc 是一个基于 Node.js 的应用程序,用来根据 JavaScript 的注释中生成 API 文档,类似 JavaDoc,这也是当前 YUI 用来生成文档的工具。生成的文档效果:

(2)如果操作系统是windows的用户,需要配置perl环境,推荐安装ActivePerl ,Linux/Unix用户则不用配置了。

(3)解压缩JsDoc,在命令提示窗口中进入JsDoc所在目录,使用如下命令即可生成Javascript代码的文档。

perl jsdoc.pl test.js

其中test.js是用于测试的js文件,如果成功则在该目录下生成js_docs_out目录,里面包含生成的文档。

(4)如果生成失败,产生如下错误信息:

Can't locate HTML/Template.pm in @INC ......

需要配置HTML::Template模块,配置方法为:

进入perl的Package Manager,可以使用命令ppm,也可以点击开始菜单——ActivePerl 5.8.8 Build 817——Perl Package Manager。然后使用install命令安装HTML::Template模块,代码如下:

C:\>ppm

PPM>install HTML-Template

PPM>quit

具体的参数及用法可以查看JsDoc的官方网站。

总结:最终采用作用域的分析方式。即 函数调用 或 函数定义 被作为一个作用域。它们之前的 @class 将被理解为这个作用域内成员的父成员。