小结下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无法真正保证一个值是常量。

@ignoreJSDoc会忽略有这个标记的函数。

具体使用方法如下：

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

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

perljsdoc.pltest.js

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

3、如果生成失败，产生如下错误信息：

Can'tlocateHTML/Template.pmin@INC......

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

进入perl的PackageManager，可以使用命令ppm，也可以点击开始菜单——ActivePerl5.8.8Build817——PerlPackageManager。然后使用install命令安装HTML::Template模块，代码如下：

C:\>ppm

PPM>installHTML-Template

PPM>quit

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

有个不错的连接:

blog.tugai.net/2010/01/08/jsdoc-toolkit-usage/