gentsdoc
v0.1.1
Published
generate typescript document
Downloads
7
Readme
gentsdoc
该工具用于把ts文件生成markdown类型的文档，也可生成独立的api.html文件，如果生成markdown文档，后续可以通过markdown转html文件，同时可以根据数据结果生成全文档html页面，对vue/react/nodom等框架的路由支持较好。
安装
- 安装gentsdoc，输入 npm install gentsdoc -g。
用法
- 输入gentsdoc -i，进行配置文件初始化，初始化生成genconfig.json文件，用户可修改配置文件。
- 输入gentsdoc -g，生成文档。
genconfig.json文件
配置项说明：
- language：语言 zh(中文) en(英文)
- src：源ts文件目录
- dst:存储markdown文件的目录
- html:如果需要转html，则此项必需配置，html格式为:{dst:html存放路径,title:html标题}
- baseUrl：基础路径，生成文件内部和文件间超链接时需要
- fileSuffix：路径后缀名，比如".html"，如果最后由markdown文件生成html文件，则可能需要url指向为html文件
- showPrivate：是否显示私有属性和方法
- defaultSince：默认版本号，如果有@since，则显示@since值，否则显示defaultSince，如果不设置，则不显示
- excludeTags：不添加到文档的注释标签，如["excludeone","author","date"]
注释标签
注释标签以“@”开始，下表是gentsdoc支持注释标签。
gentsdoc支持class、interface、class method、class property、function(外置函数)的注释。
标签名|作用于|描述 -|-|- @since|all|起始版本号 @deprecated|all|废弃于 后面给版本号，废弃说明换行写，可以多行 @param|class method,function|参数 @returns|class method,function|返回值 @throws|class method,function|异常 @exclude|all|整段注释不加入文档
gentsdoc支持自定义标签，不做特殊处理，只是在文档中增加标题进行显示
注释说明
注释采用“/**”开头，“*/”结束，如:
/**
* classA是一个测试类
* @remarks
* 主要用于测试用，测试方式如下
*/ 注释中支持markdown的样式，如代码、表格、列表等，只需要按照markdown的方式写即可。
类(接口)的注释
类和接口的注释一样，注释第一段显示为描述(Description)，后面可以追加用户想追加的标签，如下例中的@remark,@example，文档中会显示remark和example标题。
/**
* 这一段显示为Description
* @remark
* 这一段显示在remark
* @example
* 使用方式如下: 这一段会显示为代码
* ```
* let r = new ClassA(1,'aaa');
* r.show();
* ```
*/
class ClassA{
} 方法(函数)的注释
类内部的函数称为方法，类外部的函数称为外置函数。
/**
* 这一部分加入方法描述(Description)
* 可以加入例子代码
* @param paramName1 这是参数1
* @param paramName2 这是参数2
* 注释内容支持多行
* @returns 返回
* @throws NoomiError
*/
show(id:number,name:string,desc?:string){
...
}属性的注释
/**
* 这是一个属性
*/
propName:string;完整示例
/**
* aop 切点类
* @examplecode
* ```typescript
* new AopPointcut('logpoint',['/*']);
* ```
* @exampletable
* 支持表格格式显示
*
* 参数名|类型|参数说明
* -|-|-
* id|string|切点id
* expressions|Array<RegExp>|切点拦截表达式
* @examplelist
* 支持列表
* + 列表1
* + 列表2
* + 列表3
*
* @author fieldyang 默认不添加到文档，参考excludeTags配置
* @date 2020-01-20 默认不添加到文档
* @since 0.5.5
* @deprecared 1.2.3
* 这个是废弃的说明，可以多行
* 继续说明废弃原因
*/
class AopPointcut{
/**
* 切点id
*/
id:string;
/**
* 表达式数组（正则表达式）
*/
expressions:Array<RegExp> = [];
/**
* 通知数组
*/
advices:Array<IAopAdvice> = [];
/**
* 构造器
* @param id 切点id(唯一)
* @param expressions 该切点对应的表达式数组，表达式为正则表达式串
*/
constructor(id:string,expressions:Array<string>){
this.id = id;
if(!expressions){
throw new NoomiError("2001");
}
if(!Array.isArray(expressions)){
expressions = [expressions];
}
expressions.forEach((item)=>{
if(typeof item !== 'string'){
throw new NoomiError("2001");
}
this.expressions.push(Util.toReg(item));
});
}
/**
* 匹配方法是否满足表达式
* @param instanceName 实例名
* @param methodName 待检测方法
* @returns 匹配返回true，否则返回false
*/
match(instanceName:string,methodName:string):boolean{
for(let i=0;i<this.expressions.length;i++){
if(this.expressions[i].test(instanceName + '.' + methodName)){
return true;
}
}
return false;
}
/**
* 给切点添加通知
* @param advice 通知对象
*/
addAdvice(advice:IAopAdvice):void{
this.advices.push(advice);
}
}输出文件说明
src目录下所有ts文件包含的类、接口都会生成独立的markdown文件，所以需要保证类和接口文件名的唯一性。
为方便后续处理，同时生成data.json文件，data.json文件包含4个部分：
- funcs:外置函数数组
- classes:类数组
- interfaces:接口数组
- enums:枚举类型数组
每个数组对象包含:
- title:类/接口/函数名
- url:url，该url组成格式为baseUrl+title+fileSuffix。例:genconfig.json中设置baseUrl为'/api/'，fileSuffix为'.html'，类名为ClassA，则url为/api/ClassA.html。
css支持
gentsdoc支持css，以适应markdown转换成html后的效果需求。以下列表中的css class需要用户自行设置。
css类名|作用于 -|- since|开始于 modifier|修饰符 datatype|数据类型 deprecated|废弃于 deprecatedtip|废弃说明 notes|注释，用于枚举类型的注释内容样式
版本
0.0.6
- 修复函数返回值解析bug
- 修改类设置since而属性和方法不设置since的bug
- 增加enum识别
- 增加类的属性值
- 增加类属性的类型
0.0.7
- 修复class或interface定义不换行识别bug
- 修复内部url生成错误
0.0.8
- 增加deprecated(废弃)注释
0.0.9
- 增加一键生成html文档，需要在配置文件中配置html项；
- 修复map内自定义类型无法链接bug。
0.1.0
- 更改readme。
0.1.1
- 修复since和deprecated内容bug;
- 修改html样式表；
- 修改枚举类型生成的内容。
转换成html
请使用markdown转html工具进行html转换。
文档效果
- 生成 markdown 转换后: http://www.noomi.cn/webroute/api/closeConnection
- 直接生成html格式 : http://www.noomi.cn/relaen/api.html