前言
对于使用JAVA的人来说,查看JavaDoc文档开发非常方便。当我们开发WEB应用的时候,需要javascriptAPI文档开发。在此,我选择了jsDoc-toolkit生成相关文档。
环境:win7,jdk1.7
我在这里就不讲解jdk的安装和配置了,这样的文章太多了。
简介
JsDoc Toolkit 是一款辅助工具,你只需要根据约定在 JavaScript 代码中添加相应的注释,它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像,没错,JsDoc Toolkit 就是基于 JavaDoc 开发的。
下载地址
http://code.google.com/p/jsdoc-toolkit/
我这里提供一个版本,提供给上google不方便的人
目录结构
app : 存放的是js文件。包括一些实例文件和读取js和模板生成文档的js文件。
conf : 提供默认的配置的文件。
java : 存放的是“rhino”这是一个脚本java写的javascript脚本引擎,用来提供js的运行环境。
templates : 存放生成文档的模板,根据不同的模板可以生成html xml等各种类型文档。
jsrun.jar,jsdebug.jar : 生成的入口调用了rhino框架和js文件
工作模式
通过一段java代码(jsrun.jar)调用rhino框架(该框架提供了一个运行javascript的环境),然后再运行javascript读取生成文档的javascript文件和模板文件生成文档。
注释标签
这里的标签是指约定的注释标签,只有写了这些标签, JsDoc Toolkit 才能根据这些标签来生成正确的文档,比如在 @example 之后跟一段小的代码例子。
可用标签列表:http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
使用
首先切换到当前目录下,windows执行下面命令
java -jar jsrun.jar app\run.js -a -e=GB18030 -t=templates\jsdoc mycode/*.js
如果成功的话,你就会看到当前文件夹里多出了一个叫做 out 的文件夹,生成的文档就在里面了!然后你就可以在浏览器中查看了。
说明:
“java -jar jsrun.jar app/run.js” :固定代码,每次运行时都必须含有的。
-a 或者 –allfunctions :为全部函数生成文档,包括那些没有写注释的。
-c 或者 –conf :使用配置文件
-d= 或者 –directory=:指定生成文档的输出目录,默认是 “out”
-e= 或者 –encoding=:指定编码方式,这里对应的是GB18030 默认的是utf-8
-n 或者 –nocode :忽略所有代码,只为有 @name 标签的注释生成文档。
-o= 或者 –out= : 将日志信息输出到指定文件
-q 或者 –quiet : 不输出任何信息,包括警告。
-t= 或者 –template= :指定文档的模板,这个参数必须提供
这里的mycode/*.js表示在mycode目录下的全部javascript文件
执行完毕后将文档结果默认输出到/out/jsdoc目录下。
查看帮助
java -jar jsrun.jar app/run.js --help
/** This is a description of the foo function. */ function foo() { } /** * Represents a book. * @constructor @author zeromike * @param {string} title - 书名. * @param {string} author - 作者. */ function Book(title, author) { }
JS方法参数配置
名称 描 述
@param @argument 指定参数名和说明来描述一个函数参数
@returns 描述函数的返回值
@author 指示代码的作者
@deprecated 指示一个函数已经废弃,而且在将来的代码版本中将彻底删除。要避免使用这段代码
@see 创建一个HTML链接,指向指定类的描述
@version 指定发布版本
@requires 创建一个HTML链接,指向这个类所需的指定类
@throws @exception 描述函数可能抛出的异常的类型
{@link} 创建一个HTML链接,指向指定的类。这与@see很类似,但{@link}能嵌在注释文本中
@fileoverview 这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记,则指定该文档块的余下部分将用来提供这个文件的概述
@class 提供类的有关信息,用在构造函数的文档中
@constructor 明确一个函数是某个类的构造函数
@type 指定函数的返回类型
@extends 指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息,不过,在某些情况下则必须使用这个标记
@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中,除非运行JSDoc时提供了--private命令行选项
@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量
@ignore JSDoc忽略有这个标记的函数
五 、注释以/**开头,以*/结束,关键字以@开头
参考网站:http://usejsdoc.org
-------------------------------------------------------如果安装nodejs----------------------------------------------------
可以使用grunt-jsdoc插件生成API
https://github.com/krampstudio/grunt-jsdoc
--------------------------------------------------------------------------------------------------------------------------------
参考文章:
http://www.cnblogs.com/rainman/archive/2011/08/14/2137934.html
http://www.cnblogs.com/hxling/archive/2012/11/27/2791067.html
相关推荐
JavaScript文档工具(JS Doc工具)是开发者用于生成代码注释的标准化方式,它能自动生成API文档,使得团队成员能够更好地理解和使用代码库。本文主要介绍`jsdoc-toolkit`,一个早期流行的JS Doc实现,以及如何使用它...
本文将详细介绍`jsdoc-toolkit`,一个早期流行的JavaScript文档生成工具,并提供一些使用指导。 `jsdoc-toolkit`是一款基于JavaScript的文档生成工具,它解析JavaScript源代码中的JSDoc注释,然后根据这些注释生成...
JSdoc-Toolkit是一款强大的JavaScript文档生成工具,它基于JSDoc规范,用于从注释中提取代码信息,并生成清晰、结构化的API文档。通过在代码中添加特定格式的注释,开发者可以方便地为项目创建专业级别的文档,提高...
JsDoc Toolkit 是一款功能强大的文档生成工具,它能够帮助开发者根据预定义的注释格式(即JsDoc规范)自动生成高质量的API文档。这对于提高代码可读性、维护性和团队协作效率具有重要意义。本文将详细介绍JsDoc ...
现有的API文档生成技术,如Java的javadoc,JavaScript的Jsdoc Toolkit等,通过在代码中添加特定标记来辅助生成文档,但这种方式增加了开发者的工作负担。 在API文档生成过程中,编译原理起着重要作用。词法分析和...
JsDoc Toolkit 是一个强大的工具,专为JavaScript开发者设计,旨在简化API文档的创建过程。这款开源工具允许开发者通过在源代码中嵌入特定的注释格式,自动生成结构化的、易于理解的文档。下面我们将深入探讨JsDoc ...
总的来说,JSDoc Toolkit 是一个强大的文档生成解决方案,特别是对于那些使用JavaScript进行大型项目开发的团队,它能够帮助他们构建清晰、详尽的API文档,提升团队协作效率,降低维护成本。通过深入学习和掌握JSDoc...
jsdoc_toolkit Cocos2d-JS API jsdoc_toolkit 1. 克隆jsdoc_toolkit.git仓库 2. 拷贝仓库到cocos2d-js仓库下frameworks/cocos2d-html5/tools/目录下 3. 打开终端 cd 到 jsdoc_toolkit。 输入 ant 回车
现有的API文档生成工具,如Java的javadoc和JavaScript的Jsdoc Toolkit,通过注解方式帮助生成文档。然而,这种方法增加了编写负担。API文档生成涉及到编译原理,包括词法分析和语法分析。词法分析器将源代码分解成...
目前国外最有名的 JS 文档生成项目为 Jsdoc Toolkit,它的工作原理是在书写文档的时候额外提供一些标记,以让文档生成工具更好地理解,确保最后生成的文档是正确的。 编译原理 编译是为了解析源码,并根据源码生成...
Java Runtime版本1.6或更高版本用于JsTestDriver,闭包编译器和jsdoc-toolkit 制作方法及使用方法 $ make $ cp src/linear.min.js /path/to/somewhere 制定目标 全部与包装相同笔记linear.js和msgpack.codec.js由...
3. **编写标准文档注释**:使用jsdoc-toolkit等工具生成API文档,为函数、方法提供详细的注释,包括参数、返回值和描述。这对于外部开发者理解和使用你的代码至关重要,同时也方便团队内部的代码维护。 4. **使用有...
JavaScript文档工具(通常被称为JSDoc)是一种用于生成基于源代码注释的API文档的工具。它使用特定的注释语法来解析JavaScript代码,并自动生成详细的文档,方便开发者理解和使用项目中的函数、类和模块。JavaScript...
JsDoc是一种用于JavaScript编程的文档生成工具,它允许开发人员按照特定的注释规范在源代码中添加元数据,然后自动生成结构化的API文档。这个工具极大地提高了代码的可读性和维护性,尤其对于大型项目或者开源项目而...
标准的文档注释可以生成易于其他团队成员阅读的文档,比如使用jsdoc-toolkit工具。完整的注释有助于团队成员理解方法的参数和实现细节,方便未来对代码的维护和升级。特别是针对公开API的文档,这些文档不仅需要被...
3. **使用标准的文档注释**:使用jsdoc-toolkit等工具,遵循JSDoc规范进行注释,以提供函数参数、返回值等信息,方便代码提示和生成API文档。良好的注释有助于团队间的沟通,便于代码理解和维护。 4. **使用规范有...