`

jsdoc-toolkit生成javascriptAPI文档

阅读更多

          

 前言

         对于使用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

  • 大小: 28 KB
  • 大小: 2.3 KB
  • 大小: 53 KB
  • 大小: 13.8 KB
  • 大小: 17.9 KB
  • 大小: 49.5 KB
1
2
分享到:
评论
1 楼 wangyudong 2017-11-27  
很多API doc生成工具生成doc需要重度依赖代码里加注解的方式,并且不支持自动化测试RESTful API。

之前习惯用一款名字为 WisdomTool REST Client,它能够基于测试过的历史记录自动生成精美的RESTful API文档,完全不用在代码里加注解,支持自动化测试RESTful API,输出精美的测试报告。
轻量级的工具,功能却很精悍哦!

https://github.com/wisdomtool/rest-client

Most of API doc tools do not support automated testing.

Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

Lightweight tool with very powerful features!

https://github.com/wisdomtool/rest-client

相关推荐

    js doc 工具推荐及使用(一):jsdoc-toolkit

    JavaScript文档工具(JS Doc工具)是开发者用于生成代码注释的标准化方式,它能自动生成API文档,使得团队成员能够更好地理解和使用代码库。本文主要介绍`jsdoc-toolkit`,一个早期流行的JS Doc实现,以及如何使用它...

    js doc工具推荐及使用(一):jsdoc-toolkit

    本文将详细介绍`jsdoc-toolkit`,一个早期流行的JavaScript文档生成工具,并提供一些使用指导。 `jsdoc-toolkit`是一款基于JavaScript的文档生成工具,它解析JavaScript源代码中的JSDoc注释,然后根据这些注释生成...

    jsdoc-toolkit

    JSdoc-Toolkit是一款强大的JavaScript文档生成工具,它基于JSDoc规范,用于从注释中提取代码信息,并生成清晰、结构化的API文档。通过在代码中添加特定格式的注释,开发者可以方便地为项目创建专业级别的文档,提高...

    JsDoc-Toolkit标签一览表

    JsDoc Toolkit 是一款功能强大的文档生成工具,它能够帮助开发者根据预定义的注释格式(即JsDoc规范)自动生成高质量的API文档。这对于提高代码可读性、维护性和团队协作效率具有重要意义。本文将详细介绍JsDoc ...

    本科毕业论文---javascript在线api文档生成文献综述.doc

    现有的API文档生成技术,如Java的javadoc,JavaScript的Jsdoc Toolkit等,通过在代码中添加特定标记来辅助生成文档,但这种方式增加了开发者的工作负担。 在API文档生成过程中,编译原理起着重要作用。词法分析和...

    jsdoc_toolkit

    JsDoc Toolkit 是一个强大的工具,专为JavaScript开发者设计,旨在简化API文档的创建过程。这款开源工具允许开发者通过在源代码中嵌入特定的注释格式,自动生成结构化的、易于理解的文档。下面我们将深入探讨JsDoc ...

    jsdoc_toolkit-2.4.0.zip

    总的来说,JSDoc Toolkit 是一个强大的文档生成解决方案,特别是对于那些使用JavaScript进行大型项目开发的团队,它能够帮助他们构建清晰、详尽的API文档,提升团队协作效率,降低维护成本。通过深入学习和掌握JSDoc...

    jsdoc_toolkit:Cocos2d-js 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 回车

    javascript在线api文档生成文献-综述设计论文.doc

    现有的API文档生成工具,如Java的javadoc和JavaScript的Jsdoc Toolkit,通过注解方式帮助生成文档。然而,这种方法增加了编写负担。API文档生成涉及到编译原理,包括词法分析和语法分析。词法分析器将源代码分解成...

    JavaScript在线API文档生成文献综述.doc

    目前国外最有名的 JS 文档生成项目为 Jsdoc Toolkit,它的工作原理是在书写文档的时候额外提供一些标记,以让文档生成工具更好地理解,确保最后生成的文档是正确的。 编译原理 编译是为了解析源码,并根据源码生成...

    linear-js:msgpack-rpc +α用于JavaScript语言

    Java Runtime版本1.6或更高版本用于JsTestDriver,闭包编译器和jsdoc-toolkit 制作方法及使用方法 $ make $ cp src/linear.min.js /path/to/somewhere 制定目标 全部与包装相同笔记linear.js和msgpack.codec.js由...

    JavaScript 开发规范要求.docx

    3. **编写标准文档注释**:使用jsdoc-toolkit等工具生成API文档,为函数、方法提供详细的注释,包括参数、返回值和描述。这对于外部开发者理解和使用你的代码至关重要,同时也方便团队内部的代码维护。 4. **使用有...

    javascript document tool

    JavaScript文档工具(通常被称为JSDoc)是一种用于生成基于源代码注释的API文档的工具。它使用特定的注释语法来解析JavaScript代码,并自动生成详细的文档,方便开发者理解和使用项目中的函数、类和模块。JavaScript...

    JSDoc 介绍使用规范JsDoc的使用介绍

    JsDoc是一种用于JavaScript编程的文档生成工具,它允许开发人员按照特定的注释规范在源代码中添加元数据,然后自动生成结构化的API文档。这个工具极大地提高了代码的可读性和维护性,尤其对于大型项目或者开源项目而...

    JavaScript 开发规范要求(图文并茂)

    标准的文档注释可以生成易于其他团队成员阅读的文档,比如使用jsdoc-toolkit工具。完整的注释有助于团队成员理解方法的参数和实现细节,方便未来对代码的维护和升级。特别是针对公开API的文档,这些文档不仅需要被...

    JavaScript开发规范要求(规范化代码)

    3. **使用标准的文档注释**:使用jsdoc-toolkit等工具,遵循JSDoc规范进行注释,以提供函数参数、返回值等信息,方便代码提示和生成API文档。良好的注释有助于团队间的沟通,便于代码理解和维护。 4. **使用规范有...

Global site tag (gtag.js) - Google Analytics