JS文档生成工具JSDoc

开发文档撰写的重要性是显而易见的，特别是针对团队的协作开发，不仅能提高团队开发效率，还可以方便他人接手项目。在自动化的今天，我们不需要手工去撰写文档，只需要编写代码的同时按照一定的规则进行注释，就可以通过工具自动生成一份详细的文档，这是很惬意的事，不是么？

我还有一个更好的基于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会忽略有这个标记的函数。