一.前言
对于使用JAVA的人来说,查看JavaDoc文档开发非常方便。当我们开发WEB应用的时候,需要javascriptAPI文档开发。可选择jsDoc-toolkit生成相关文档。
二.简介
JsDoc Toolkit 是一款辅助工具,你只需要根据约定在 JavaScript 代码中添加相应的注释,它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像,没错,JsDoc Toolkit 就是基于 JavaDoc 开发的。
三.目录结构
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
Js代码
book.js
/** 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) { }
person.js
/** This is a description of the food function. */ function food() { } /** * Represents a person. * @constructor @age zeromike * @param {string} name - 姓名. * @param {string} age - 年龄. */ function person(name, age) { }
运行:
运行结果:
打开out目录
打开index.html
点击person链接
七.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
相关推荐
NULL 博文链接:https://gogo1217.iteye.com/blog/1164746
前端开源库-grunt-jsdoc-to-markdowngrunt jsdoc to markdown,markdown api文档生成器,适合Github项目
JsDoc Toolkit 是一个把js描述格式化成文档的工具。开发者只需按JsDoc的规范写好注释就可以很方便导出文档。它是google 推荐的JsDoc生成工具。
表达jsdoc-swagger 使用此库,您可以使用来记录您的快速端点,而无需编写YAML或JSON。 您可以在每个端点上编写jsdoc注释,该库将创建swagger UI。 先决条件 该库假定您正在使用: 安装 npm i express-jsdoc-...
szn-util-jsdoc2 Javascript 自动文档工具 jsdoc-toolkit-2 debian 包源码 # git clone git@github.com:seznam/szn-util-jsdoc2.git# cd szn-util-jsdoc2# dpkg-buildpackage -us -uc -rfakeroot
NULL 博文链接:https://bijian1013.iteye.com/blog/2178669
前端开源库-jsdoc-xjsdoc-x,解析器,用于通过jsdoc的explain(-x)命令从文档代码中输出定制的javascript对象。
从注释的源代码生成markdown API文档。 对于将API文档注入项目自述文件很有用。 概要 1.使用有效的jsdoc注释记录代码。 /** * A quite wonderful function. * @param { object } - Privacy gown * @param { ...
前端开源库-jsdoc-webpack-pluginjsdoc webpack插件,jsdoc webpack插件
用于 jsdoc-to-markdown 的西兰花插件安装$ npm install --save broccoli-jsdoc-to-markdown用法JavaScript var broccoli - jsdoc - to - markdown = require ( 'broccoli-jsdoc-to-markdown' ) ;broccoli - jsdoc -...
Java JsDoc Toolkit v2.0文档工具下载,可以把javaScript描述信息格式化,开发者只要按JsDoc规范写好注释就可以很方便的导出文档。这是Java版本的,附有JAVA源文件,这款工具也是google 极力推荐的JsDoc输出工具。
$ npm install --save-dev jsdoc jsdoc-vuejs 您还需要安装与您的Vue版本匹配的vue-template-compiler : # if you use Vue 2.5.21 $ npm install --save-dev vue-template-compiler@2.5.21 用法 您应该更新JSDoc...
NULL 博文链接:https://blueskylan.iteye.com/blog/353482
JsDoc Toolkit 是一个把js描述格式化成文档的工具。开发者只需按JsDoc的规范写好注释就可以很方便导出文档。这个JsDoc是Java版本的,用起来方便一些。这也是 google 推荐的 JsDoc 输出工具
chm api jsf myfaces jsdoc
jsdoc-vuedoc jsdoc插件使用@ vuedoc / md。 依赖项[电子邮件保护]:支持异步/等待功能。 @ vuedoc / md。 安装npm i jsdoc-vuedoc -D或jsdoc-vuedoc jsdoc插件使用@ vuedoc / md。 依赖项[电子邮件保护]:支持异步/...
jsdoc-tsd 安装 您可以从npm安装此模块: $> npm install @otris/jsdoc-tsd 用法 要使用此模块,只需将这个项目指定为jsdoc输出的模板。 要从命令行使用此模板,请运行 $> jsdoc -t node_modules/@otris/jsdoc-...
grunt-jsdoc-to-markdown 一个针对grunt插件。 接受与相同的选项。安装$ npm install grunt-jsdoc-to-markdown --save-dev用法示例Gruntfile.js : 'use strict'module . exports = function ( grunt ) { grunt . ...
该提供了一种在静态网站上生成javascript代码文档的方法。 先决条件 要生成良好的文档,请阅读。 必须安装Node.js和NPM 。 跑步 首先通过执行以下命令来构建项目: npm run build 然后打开docs目录并运行index....