JSDoc 使用手册

JSDoc 简介

JSDoc (JavaScript Document)是JavaScript的API文档生成器，类似于Javadoc或phpDocumentor。 您可以在代码本身旁边直接将文档注释添加到源代码中。 JSDoc工具将扫描您的源代码并为您生成一个HTML文档网站。

JSDoc安装

$提示：$ 需要先安装node.js，点击前往安装

# 全局安装jsdoc
npm install -g jsdoc 

JSDoc 使用

1. 新建一个文件hello.js

   // 文件hello.js
   
   /**
   *@author joe
   */
   function sayHello(){
       console.log("Hello World")
   }
   

2. 生成api文档

   jsdoc hello.js -d ./api/
   

3. 浏览api文档
   使用浏览器打开 ./api/index.html

Block Tags

tag	description
@abstract	描述这个成员必须在继承的子类中实现(或重写)
@access	指定该成员的访问级别(私有private、公共public、或保护protect)
@alias	标记成员有一个别名
@async	表示一个函数是异步的
@augments	指明这个子类继承自哪个父类，后面需要加父类名。
@author	指明项目的作者
@borrows	指明这个对象使用另一个对象的某些东西。
@callback	描述一个回调函数。
@class	此函数旨在需要使用“new”关键字调用，即构造函数。
@classdesc	用于为类提供一个描述，这样和构着函数的描述区分开来
@constant	指明这个对象是一个常量。
@constructs	描述这个函数成员将成为类的构着函数。
@copyright	描述一个文件的版权信息。
@default	描述默认值。
@deprecated	指明代码被弃用。
@description	描述一个标识符。
@enum	描述一个相关属性的集合。
@event	描述一个事件。
@example	提供一个如何使用描述项的例子。
@exports	标识一个由JavaScript模块导出的成员。
@external	用来标识一个在当前包外部定义的类，命名空间，或模块。
@file	描述一个文件。
@fires	描述事件这个方法可能会触发。
@function	描述一个函数或方法。
@generator	表示函数是生成器函数。
@global	指定一个文档的标识是全局性的标识。
@hideconstructor	指示不应显示构造函数。
@ignore	忽略文档中的一个标识。
@implements	指示一个标识是实现一个接口。
@inheritdoc	指明这个标识应该继承其父类的方法。
@inner	描述一个内部对象。
@instance	标明该标识符作为它父标识符的实例成员。
@interface	使一个标识符作为其他标识符的一个实现接口。
@kind	指明标识类型。
@lends	将一个字面量对象的所有属性标记为某个标识符（类或模块）的成员。
@license	标识你的代码使用何种软件许可协议。
@listens	指示一个标识监听指定的事件。
@member	记录一个成员。
@memberof	标明这个标识属于哪个父级标识。
@mixes	此对象混入了另一个对象的所有成员。
@mixin	记录一个mixin（混入）对象。
@module	记录一个JavaScript模块。
@name	记录一个对象的名称。
@namespace	记录一个命名空间对象。
@override	指明一个标识符覆盖其父类同名标识符。
@package	该符号是软件包专用的。
@param	记录传递给一个函数的参数。
@private	标记标识符为私有。
@property	记录一个对象的属性。
@protected	标记标识符为受保护的。
@public	标记为公开的。
@readonly	标记一个标识符为只读。
@requires	指示这个文件需要一个JavaScript模块。
@returns	描述一个函数的返回值。
@see	指明可以参考另一个标识符的参考文档，或者一个外部资源。
@since	标签标明一个类，方法，或其他标识符是在哪个特定版本开始添加进来。
@static	记录一个静态成员。
@summary	完整描述的一个简写版本。
@this	指明this关键字的指向。
@thows	说明可能会被抛出什么样的错误。
@todo	记录要完成的任务。
@tutorial	插入一个到包含教程文件的链接。
@type	记录一个对象的类型。
@typedef	描述自定义类型。
@variation	区分具有相同名称的不同的对象。
@version	指明被用于表示该项的版本。
@yields	记录生成器函数产生的值。

参考文献

JSDoc中文文档