使用YUIDoc创建js文档

Posted 2021-03-18 帆酱的点滴记忆

什么是YUIDoc？

YUIDoc会根据你写的代码注释生成API文档。

YUIDoc是个NodeJS应用，能将你的JS代码中的注释生成html格式的API文档。事实上，不仅是JS，任何支持块注释的语言都能使用。

安装

要安装YUIDoc，首先要安装好NodeJS，然后使用 npm -g install yuidocjs 即可安装YUIDoc。

使用

1. 在相应的目录下输入 yuidoc . ，会在当前目录生成 out文件，里面生成注释文档
2. 在相应的目录下输入 yuidoc . –server <port>，会使用nodejs环境生成对应的网站

基本语法

详见YUIDoc官方文档

YUIDoc从源文件的多行注释中抽取到文档内容。当然，你会有些注释不想成为文档的一部分，让YUIDoc知道你的注释是非常重要的，必须以两个*开头。如下：

/**
 * YUIDoc 会认出这个
 */

/*
 * YUIDoc 不会认这个
 */

主标签

开始讲主标签之前，必须明确一点，每个注释块中能切仅有一个主标签。描述了当前代码块的作用。

@module

@module标签描述了一组关联的类（JS中并不包含类，YUIDoc把构造器归纳成类）。如果我们用YUIDoc生成UDTWO的文档，那UDTWO对象就是个module，因为他同时管理Model、Collection、View和其他类。标签后面跟着写@module的名称：

/**
 * 此处以声明一个名为UDTWO的模块
 * @module UDTWO
 */

注意：module需与method分开写，否则method无法被识别。

常用的一些标签：

标签	描述
@module 1	标明当前文件模块，在这个文件中的所有成员将被默认为属于此模块，除非另外标明
@submodule 1	针对模块的划分，处于@module之下
@class	标示一个类或一个函数
@constructor	当使用对象字面量形式定义类时，可使用此标签标明构造函数
@callback	标明此方法是一个回调函数
@event	标明一个可触发的事件函数，一个典型的事件是由对象定义的一组属性来标示。
@constant	常量标识
@member/@var	记录一个基本数据类型的成员变量
@method	标记一个方法或函数
@param	标记方法参数及参数类型
@property	标明一个对象属性
@readonly	只读
@return	标明返回值、类型及描述
@type	描述代码变量的类型
@description	如果在注释开始描述可省略此标签
@enum	一个类中属性的类型相同，使用此标签标明
@example	示例，代码可自动高了
@exports	标识此对象将会被导出到外部调用
@ignore	忽略此注释
@link	内联标签，创建一个标签。如\'{@link http://github.com Github}\'
@name	指定一段代码的名字，强制JsDoc使用此名称，而不是代码里的名称
@namespace	指定一个变量命名空间变量
@static	描述一个不需实例即可使用的变量
@summary	对描述信息的短的概述
@throws	描述方法将会出现的错误和异常
@todo	描述函数的功能和任务
@tutorial	插入一个指向向导教程的链接
@see	标签允许您引用可能与被记录的相关的另一个符号或资源

 代码实例：

/**
* 常用方法
* @module 常用方法
*/

/** 
* 数组方法
* @class 数组方法
*/


/**
 * 
 * @method arr_splice
 * @name 切割数组前n个元素
 * @param {Array} arr:需要切割的数组
 * @param {Number} n：切割前n个元素
 * @return {Array} arr:返回一个数组
 */
function arr_splice(arr,n){//arr:数组,n:切割前n个
    if(arr && arr.length>n){
        let new_arr=arr.splice(n);
        return new_arr;
    }else{
        return arr;
    }
};

export{
    arr_splice,//切割数组前n个元素
}

 运行 yuidoc .，输出一个文档项目