开发文档撰写的重要性是显而易见的,特别是针对团队的协作开发,不仅能提高团队开发效率,还可以方便他人接手项目。在自动化的今天,我们不需要手工去撰写文档,只需要编写代码的同时按照一定的规则进行注释,就可以通过工具自动生成一份详细的文档,这是很惬意的事,不是么?
我还有一个更好的基于Editplus工具的前端自动化的想法,也正在项目中实施,如果精力允许,我会慢慢的写出来,分享给需要的人。
JS的文档生成工具 常见的有以下几种:
1)JSDoc,是perl编写的,运行稳定,模板修改也挺方便,经过简单汉化和模板风格修改之后,是首选。
2)JSDoc-toolkits,Java编写的,据说是Google推荐的JS文档生成工具,经过测试,可以生成文档,但问题多多,或许是我研究的不够,在查了多处资料仍不解后放弃掉了。
3)YUIDoc,Python编写的,没有实际使用,不过相信是不错的,因为Y的工程师团队是最令我敬佩的团队之一,因为Y了解并提供了前端开发的一整套很帅的解决方案。
这三种工具都有一个简单的共同点,支持命令行模式,如此一来,结合DOS批处理或者WSH很容易整合进Editplus,不需要打开DOS窗口,只需要在Editplus中就能完成指定目录或指定文件的文档生成,剩下的就是个人的创意了。
我选择了JSDoc,JSDoc支持很多参数 ,在DOS下,转到JSDoc的目录,输入:
perl jsdoc.pl --help
Usage: jsdoc [OPTIONS] <js sourcefiles and/or directories>+
-h | --help Show this message and exit
-r | --recursive Recurse through given directories
-p | --private Show private methods and fields
-d | --directory Specify output directory (defaults to js_docs_out)
-q | --quiet Suppress normal output --page-footer Specify (html) footer string that will be added to
all docs
--project-name Specify project name for that will be added to docs
--logo Specify a path to a logo to be used in the docs
--project-summary Specify a path to a text file that contains an
overview summary of the project --no-sources Don't include the source code view
--extensions Provide a comma-separated list of file extensions
to be considered as JavaScript source files --nested-file-naming Use package-style naming (i.e. keep directory
names in the file path). This is useful if you
have multiple files with the same name, but in
different directories. This option is only useful
if --recursive is also used. --globals-name Specify a 'class name' under which all unattached
methods will be classified. The defaults to GLOBALS --format Set the output format. The options are html, xml
and xmi, defaulting to html. The others are currently
alpha software. --template-dir Provide another directory containing HTML templates
--no-lexical-privates Ignore "private" variables and functions that are
lexically defined within constructors --package-naming Use packages, with a package being defined as a class
that only contains nested classes and possibly
static members.
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会忽略有这个标记的函数。