JSDoc 3 入门

原文：http://usejsdoc.org/about-getting-started.html

入门

JSDoc3是针对JavaScriptAPI文档的生成，类似于JavaDoc或PHPDoc。您可以直接添加文档注释在你的源代码中，沿边代码自身方面。该JSDoc工具会扫描你的源代码，并生成一个完整的HTML文档的网站为您。

添加文档注释对你的代码

JSDoc的目的是记录你的JavaScript应用程序或库的API。假定你将要记录的东西，如：命名空间，类，方法，方法参数等。

JSDoc评论一般应立即放置被记录的代码之前。它必须以/ * 序列，以便由JSDoc解析器识别。注释开头/ ，/*，或超过3星级将被忽略。这是一个功能，让你压抑注释块的解析。

最简单的文件只是一个说明。

/** This is a description of the foo function. */
function foo() {
}

添加描述很简单，只要输入你想要的描述d文档注释。

特殊的“文档标签”可用于提供更多的信息。例如，如果函数是一个构造函数，你可以通过添加标记表明这一点。

使用文件标记来描述你的代码。

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

多个标签可用于增加更多的信息。查看标签词典是由JSDoc3公认的完整标签列表。

用标记添加更多的信息

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

生成一个网站

一旦你的代码是注释的，您可以使用JSDoc3工具从源码中生成的源的HTML网页。

默认情况下，JSDoc将使用“default”模板打开的文档数据转换成HTML。您可以编辑该模板，以满足你自己的需要，或者创建一个全新的模板，如果那是你喜欢的。

在命令行上运行生成文档。

./jsdoc book.js

该命令将创建一个名为“out”在当前的工作目录文件夹。在你会发现生成的HTML页面。