C#自动生成在线API文档工具

日期 版本 记录人 描述
2020/9/19 v1.0 王子豪 创建文档
2020/11/02 v1.1 王子豪 更新工具包
2021/2/3 v2.0 王子豪 修复若干问题,加入反射功能,支持泛型

0 工具原理

    读取CSharp项目生成的xml注释文件并解析,过滤需要生成文档的类、函数等注释,通过showdoc提供的http接口,最终生成在线注释文档。
    v2.0更新内容:工具会在xml文件所在目录下寻找同名dll动态库,使用反射载入该库及其依赖,修正,补充注释文档的内容。

1 注释规则

v2.0更新内容:加入反射后,可以简化注释的规则,remarks标签所起到的功能由反射取代。

1.1 showdoc

值为truefalse,默认为false,用于标识注释是否参与生成注释文档,该标签若出现在类注释中,该类的所有注释都会参与生成注释文档

showdoc标签可以作为summary标签的属性,如图所示

showdoc标签可以作为与summary同级的标签,如图所示

1.2 catalog

catalog标签格式为目录+"/"+标题,该标签若出现在类注释中,该类的所有注释都优先采用该目录和标题

catalog标签作为summary同级标签,如图所示

1.2.1 特别注意

a.参与生成注释文档却没有配置目录的注释会引起报错

b.showdoc虚拟实验室项目目录基本已经划分好,同学们尽量把生成的注释文档放在已经存在的目录中。

1.3 remarks

remarks标签用作描述字段/属性的类型,该标签只在字段/属性注释内起作用,该标签与summary标签同级,如图所示

2 C#生成在线文档工具

工具下载路径:Showdoc.rar

2.1 解压工具到项目目录下

2.2 配置showdoc的api_key,api_token

打开工具文件夹目录下的Showdoc.exe.config配置文件,配置api_key和api_token,相关值可以从showdoc项目设置内查找。

2.3 配置工具命令行启动参数

编辑Showdoc.bat批处理文件,在`start Showodc.exe `后面加上项目生成的xml注释文档路径(相对路径或绝对路径都行),若有多个项目,路径间空格隔开

PS:所需要的项目xml注释文件需要右键项目->属性->生成->勾选XML文档文件单选框