小结下javascript生成注释的工具

一般来说,javascript的注释生成工具比较少,比较麻烦,小结了一些以备用:

JS的文档生成工具常见的有以下几种:

1)JSDoc,是perl编写的,运行稳定,模板修改也挺方便,经过简单汉化和模板风格修改之后,是首选。
2)JSDoc-toolkits,Java编写的,据说是Google推荐的JS文档生成工具,经过测试,可以生成文档,但问题多多,或许是我研究的不够,在查了多处资料仍不解后放弃掉了。
3)YUIDoc,Python编写的,没有实际使用,不过相信是不错的,因为Y的工程师团队是最令我敬佩的团队之一,因为Y了解并提供了前端开发的一整套很帅的解决方案。


JSDOC:
JSDoc支持的命令属性:

命令名                描述
@param
@argument           指定参数名和说明来描述一个函数参数。
@return
@returns              描述函数的返回值。
@author               指示代码的作者。
@deprecated     指示一个函数已经废弃,不建议使用,而且在将来版本的代码中可能会彻底删除。要避免使用这段代码。
@see                    创建一个HTML链接指向指定类的描述。
@version              指定发布版本。
@requires             创建一个HTML链接,指向这个类所需的指定类。
@throws
@exception           描述函数可能抛出的异常的类型。
{@link}                创建一个HTML链接,指向指定的类。这与@see很类似,但{@link}能嵌在注释文本中。
@author                指示代码的作者。(译者注:这个标记前面已经出现过,建议去掉)
@fileoverview     这是一个特殊的标记,如果在文件的第一个文档块中使用这个标记,则指定该文档块的余下部分将用来提供文件的一个概述。
@class                  提供类的有关信息,用在构造函数的文档中。
@constructor        明确一个函数是某个类的构造函数。
@type                  指定函数的返回类型。
@extends             指示一个类派生了另一个类。通常JSDoc自己就可以检测出这种信息,不过,在某些情况下则必须使用这个标记。
@private              指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中,除非运行JSDoc时提供了—private命令行选项。
@final                  指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量。
@ignore             JSDoc会忽略有这个标记的函数。


具体使用方法如下:
1、如果操作系统是windows的用户,需要配置perl环境,推荐安装ActivePerl ,Linux/Unix用户则不用配置了。
2、解压缩JsDoc,在命令提示窗口中进入JsDoc所在目录,使用如下命令即可生成Javascript代码的文档。
                                 perl jsdoc.pl test.js
其中test.js是用于测试的js文件,如果成功则在该目录下生成js_docs_out目录,里面包含生成的文档。
3、如果生成失败,产生如下错误信息:
                                 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的官方网站。

有个不错的连接:
blog.tugai.net/2010/01/08/jsdoc-toolkit-usage/

你可能感兴趣的:(JavaScript,html,linux,python,perl)