Javascript API文档生成工具YUIDoc入门

介绍

YUIDoc是基于Nodejs的可以将文档中的注释生成API文档的工具。它可以时时预览你写入的内容,支持自定义文档模版,生成的文档清晰易用,并且不局限于你所使用的语言,只要你的代码中按照YUIDoc规范的格式来写注释就可以生成想要的API文档,因此在各团队协作中用来作为统一的文档工具再合适不过了。

YUIDoc安装

以Windows环境为例,前面提到它是基于Nodejs的,所以在安装之前你需要先下载安装Nodejs(自带npm,无需另外安装)。安装好后就可以运行以下命令来安装YUIDoc了:

运行命令后,会看到一堆GET请求,之后YUIDoc就自动下载安装到Nodejs模块目录下并且将它加入系统的环境变量里,这样你就可以在任意文件夹下使用YUIDoc命令了。

开始使用YUIDoc

到这里你就可以开始使用YUIDoc来为你的Javascript项目生成文档啦,你可以在现有或者新建的项目的js里加入YUIDoc语法格式的注释(YUIDoc语法参考),然后运行cmd,切换到项目目录下运行以下命令,API文档就可以生成了:

注意yuidoc命令后面空格加一个点,表示在当前目录下生成文档。运行命令后,YUIDoc会一次性生成该项目目录及其子目录下所有JS的文档,默认在不配置的情况下会生成在当前目录的out目录中。

实时预览

在团队协作的时候,如果你懒得去配置本地服务器,为了可以让其他成员方便的看到你的文档,可以使用YUIDoc快速构建webserver,其他人就可以通过浏览器访问到你的API文档了,具体操作是在你使用前面提到的命令生成文档后,然后执行以下命令:

上面的命令,首先是在cmd里把当前目录切换到out目录下,然后使用YUIDoc构建webserver监听端口7777,这里的端口可以是任意未被其他进程占用的端口,后面的操作就是防火墙为此端口放行,这样其他人就可以通过访问你的ip:端口看到你的API文档了。

注意事项

YUIDoc中注释块必须至少以/**(两个星号)开头,代码是以模块划分,每个模块包含对应的类,而方法和属性是属于类的,因此如果你的代码里没有类的注释,那么方法和属性的注释就会被忽略而不生成对应的API说明,YUIDoc是基于注释生成文档,所以只要你有类的注释,不管这个类的代码是否真的有存在,就可以生成文档了,对于简单的没有模块划分的JS项目来说,可以用这个技巧来生成方法的文档。

扩展阅读

用yuidoc.json配置你的YUIDoc:http://yui.github.io/yuidoc/args/index.html#json

如需转载,请注明出处:https://i.wanz.im/2013/05/15/documenting_javascript_with_yuidoc/

发表评论

电子邮件地址不会被公开。 必填项已用*标注

Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.