JsDoc 导出API 基础操作 格式规范 基础学习

很高兴webstorm可以直接使用,为了导出api记录一下

1.安装

命令行 cnpm install -g jsdoc

2.导出文档

命令行 jsdoc {需要转为API的文件} -d {输出路径}

示例 :

>jsdoc zhiu_Foundation/ZhiUTech.js -d ZhiU_Engine/zhiu_API1

 

基础使用

/** 写一下下面的意思

 *@function 方法名称

*@param {参数类型} 参数名称 参数含义

*@return {返回类型} 返回名称 返回含义

*/

 

参数说明 :

1.@function

表示该下方结构为function

例:

@function funcName

2.@name

可以跟在@function 下方标识方法名称

例:

@function

@name funcName

也可以标识下方对象名称

例:

@name objectName

3.@summary

用于标注下方结构的作用

例:

@summary A concise summary.

4.@param

用于描述参数的 类型 名称 作用

例:

@param {string} variableName variableEffect

function Func(variableName){}

如果参数为对象并含有属性

例:

@param {Person} person A person variable

@param {string} person.Name his name

@param {int} person.Age his age

function Func(person){}

如果含有可选参数

例:

@param {string} [variableName] variableEffect

如果含有可选参数并且有默认值

例:

@param {string} [variableName=LJason] variableEffect

如果参数的类型有多重选择

例:

@param {string | string[]} variableName variableEffect

如果参数的类型不限

例:

@param {*} variableName variableEffect

5.@callback

用于描述回调函数

例:

(全局回调)

/**

 * this is a load success callback

 * @callback SuccessAction

 * @param {number} responseCode

 * @param {string} responseMessage

 */

调用:

/** @function LoadModel

 * @summary this func can load model

 * @param {SuccessAction} callback model loaded callback

 */

function LoadModel(callback){}

 

(局部回调)

/**

 * this is a load success callback

 * @callback Object~SuccessAction

 * @param {number} responseCode

 * @param {string} responseMessage

 */

调用:

/**

 * @summary this func can load model

 * @param {Object~SuccessAction} callback model loaded callback

 */

Object.load=function(callback){}