jsdoc_eye-1024x410

JS 文档生成工具：JSDoc 介绍

JSDoc 是一个根据 javascript 文件中注释的信息，生成 API 文档的工具。生成的文档是 html 文件。类似 JavaDoc 和 PHPDoc。

用法

/** 一坨注释之类的 */ JSDoc 会从/**开头的注释中抽取信息。用/*,/***开头的注释会被 JSDoc 忽略。 如

1
2
3
4
5
6
7
8
9
10
11
12
/** This is a description of the foo function. */
function foo() {
}

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

生成 API 文档

我是用的基于 Grunt 的插件：grunt-jsdoc。 具体用法见这里。下面是我的 grunt-doc 的配置

1
2
3
4
5
6
'jsdoc': {
    src: ['my-lib/*/*.js', '!my-lib/doc/**/*.js'],
    options: {
        destination: 'my-lib/doc'
    }
}

使用标签

标签就是一些以@开头的命令。 如果你想描述方法的参数，可以这样使用

1
2
3
4
5
6
/**
 * @param {string} somebody - Somebody's name
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

somebody 是参数名 {string} 是参数的类型 Somebody's name 参数的描述 下面描述一些常用的标签

@param

方法的参数描述。 用法: @param {类型} 参数名 - 描述

  • 如果参数名以[]来包围，表示这参数是可选的
  • 参数名=默认值，表示参数的默认值
  • {类型1类型2}，表示多个类型

更多

@returns

方法的返回值。 用法 : @returns {类型} 返回值描述

@file

文件描述。 用法 ： @file 文件描述

@todo

描述一些要做的事。 用法 ： @todo 描述

@author

作者。 用法 ： @author 作者

@constructor

表明这个方法是个构造器。 用法 ： @constructor 所有标签用法见这里

完整 demo 的源码

见这里。其中 doc 文件夹下的内容是 grunt-doc 生成的。

资源