API文档生成(c# dll)
一、Sandcastle
这个是c#类库方法根据注释生成帮助文档的工具,我们经常会遇到把DLL或者API提供给别人调用的情况,通过在方法中添加注释,然后再用Sandcastle 来自动生成文档给调用者,如下图:
图1:这是Sandcastle Help File Builder软件界面
图2:这是生成的chm文档
还可以直接给出示例代码:
图3:还可以直接生成网页
二、下载安装
下载地址:
Help File Builder and Tools v2021.4.9.0最新版本
下载链接:https://github.com/EWSoftware/SHFB/releases
单纯Sandcastle好像是没有界面的, 这个链接提供的下载可以包含图形界面。
注意:如果需要生成chm还需要微软的 MicrosoftHTMLHelpWorkshop 支持,Sandcastle生成时会自动去查找MicrosoftHTMLHelpWorkshop 的安装目录。
安装:
安装很简单,两个软件都只需要直接点击“下一步”即可安装完成。
三、Sandcastle配置
安装好软件后可以根据自己的需要配置相应的参数。
默认情况下dll中所有方法和属性都会生成对应文档,也可以根据自己需要只把DLL中需要的类或方法生成文档,可通过如下图配置:
在左侧把需要的类或方法勾选就行了:
在使用工具生成文档前,别忘了在VS中要作简单配置,才能生成DLL对应的XML配置文件,vs配置方法如下:
在VS中右键项目属性:
把"XML documentation file:"勾选,当编译时在生成DLL的同时还会生成一个和dll同名的xml配置文件。
在Sandcastle中右侧窗口右键将需要生成文档的dll和对应的xml添加进来:
点击工具栏上的
这个按钮就可以自动生成文档了。
四、C#注释规范
为了生成友好的帮助文档,注释规范自然少不了,以下是关于C#的注释规范以及各参数的说明,注释越详细,生成的文档可读性越好:
1、C#注释标记:
大家对注释应该都不陌生,在方法或者类前面三个斜杠就自动添加了常用的注释标记,如下图:
但是如果想要得到更加友好的帮助文档,注释得花点心思。
如文章开头所展示的帮助文档,部分方法的注释如下:
2、C#注释标记说明:
A.2.1.
此标记提供一种机制以指示用特殊字体(如用于代码块的字体)设置说明中的文本段落。对于实际代码行,请使用 (第 A.2.2 节)。
语法:
text
示例:
/// Class Point models a point in a two-dimensional
/// plane.public class Point
{
// ...
}A.2.2.
此标记用于将一行或多行源代码或程序输出设置为某种特殊字体。对于叙述中较小的代码段,请使用 (第 A.2.1 节)。
语法:
source code or program output
示例:
/// This method changes the point's location by
/// the given x- and y-offsets.
/// For example:
///
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
///
/// results in p's having the value (2,8).
///
///public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}A.2.3.
此标记用于在注释中插入代码示例,以说明如何使用所关联的方法或其他库成员。通常,此标记是同标记 (第 A.2.2 节)一起使用的。
语法:
description
示例:
有关示例,请参见 (第 A.2.2 节)。
A.2.4.
此标记提供一种方法以说明关联的方法可能引发的异常。
语法:
description
其中
cref="member"
成员的名称。文档生成器检查给定成员是否存在,并将 member 转换为文档文件中的规范元素名称。
description
对引发异常的情况的描述。
示例:
public class DataBaseOperations
{
///
///
public static void ReadRecord(int flag) {
if (flag == 1)
throw new MasterFileFormatCorruptException();
else if (flag == 2)
throw new MasterFileLockedOpenException();
// …
}
}A.2.5.
此标记允许包含来自源代码文件外部的 XML 文档的信息。外部文件必须是符合标准格式的 XML 文档,还可以将 XPath 表达式应用于该文档来指定应包含该 XML 文档中的哪些 XML 文本。然后用从外部文档中选定的 XML 来替换 标记。
语法:
filename" path="xpath" />
其中
file="filename"
外部 XML 文件的文件名。该文件名是相对于包含 include 标记的文件进行解释的(确定其完整路径名)。
path="xpath"
XPath 表达式,用于选择外部 XML 文件中的某些 XML。
示例:
如果源代码包含了如下声明:
/// "docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { … }并且外部文件“docs.xml”含有以下内容:
"1.0"?>
"IntList">
Contains a list of integers.
"StringList">
Contains a list of integers.
这样输出的文档就与源代码中包含以下内容时一样:
///
/// Contains a list of integers.
///
public class IntList { … }A.2.6.
此标记用于创建列表或项目表。它可以包含 块以定义表或定义列表的标头行。(定义表时,仅需要在标头中为 term 提供一个项。)
列表中的每一项都用一个 块来描述。创建定义列表时,必须同时指定 term 和 description。但是,对于表、项目符号列表或编号列表,仅需要指定 description。
语法:
term
description
term
description
…
term
description其中
term
要定义的术语,其定义位于 description 中。
description
是项目符号列表或编号列表中的项,或者是 term 的定义。
示例:
public class MyClass
{
/// Here is an example of a bulleted list:
///
///
/// Item 1.
///
///
/// Item 2.
///
///
///
public static void Main () {
// ...
}
}A.2.7.
此标记用于其他标记内,如 (第 A.2.11 节)或 (第 A.2.12 节),用于将结构添加到文本中。
语法:
content
其中
content
段落文本。
示例:
/// This is the entry point of the Point class testing program.
/// This program tests each method and operator, and
/// is intended to be run after any non-trvial maintenance has
/// been performed on the Point class.
public static void Main() {
// ...
}A.2.8.
该标记用于描述方法、构造函数或索引器的参数。
语法:
description
其中
name
参数名。
description
参数的描述。
示例:
/// This method changes the point's location to
/// the given coordinates.
///the new x-coordinate.
///the new y-coordinate.
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}A.2.9.
该标记表示某单词是一个参数。这样,生成文档文件后经适当处理,可以用某种独特的方法来格式化该参数。
语法:
name"/>
其中
name
参数名。
示例:
/// This constructor initializes the new Point to
/// (,).
///the new Point's x-coordinate.
///the new Point's y-coordinate.public Point(int xor, int yor) {
X = xor;
Y = yor;
}A.2.10.
该标记用于将成员的安全性和可访问性记入文档。
语法:
description
其中
cref="member"
成员的名称。文档生成器检查给定的代码元素是否存在,并将 member 转换为文档文件中的规范化元素名称。
description
对成员的访问属性的说明。
示例:
/// Everyone can
/// access this method.public static void Test() {
// ...
}A.2.11.
该标记用于指定类型的概述信息。(使用 (第 A.2.15 节)描述类型的成员。)
语法:
description
其中
description
摘要文本。
示例:
/// Class Point models a point in a
/// two-dimensional plane.
public class Point
{
// ...
}A.2.12.
该标记用于描述方法的返回值。
语法:
description
其中
description
返回值的说明。
示例:
/// Report a point's location as a string.
/// A string representing a point's location, in the form (x,y),
/// without any leading, trailing, or embedded whitespace.
public override string ToString() {
return "(" + X + "," + Y + ")";
}A.2.13.
该标记用于在文本内指定链接。使用 (第 A.2.14 节)指示将在“请参见”部分中出现的
文本。语法:
member"/>
其中
cref="member"
成员的名称。文档生成器检查给定的代码元素是否存在,并将 member 更改为所生成的文档文件中的元素名称。
示例:
/// This method changes the point's location to
/// the given coordinates.
///
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}/// This method changes the point's location by
/// the given x- and y-offsets.
///
///
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}A.2.14.
该标记用于生成将列入“请参见”部分的项。使用 (第 A.2.13 节)指定来自文本内的链接。
语法:
member"/>
其中
cref="member"
成员的名称。文档生成器检查给定的代码元素是否存在,并将 member 更改为所生成的文档文件中的元素名称。
示例:
/// This method determines whether two Points have the same
/// location.
///
///
public override bool Equals(object o) {
// ...
}A.2.15.
可以用此标记描述类型的成员。使用 (第 A.2.11 节)描述类型本身。
语法:
description
其中
description
关于成员的摘要描述。
示例:
/// This constructor initializes the new Point to (0,0).
public Point() : this(0,0) {
}A.2.16.
该标记用于描述属性。
语法:
property description
其中
property description
属性的说明。
示例:
/// Property X represents the point's x-coordinate.
public int X
{
get { return x; }
set { x = value; }
}A.3. 处理文档文件
文档生成器为源代码中每个附加了“文档注释标记”的代码元素生成一个 ID 字符串。该 ID 字符串唯一地标识源元素。文档查看器利用此 ID 字符串来标识该文档所描述的对应的元数据/反射项。
文档文件不是源代码的层次化表现形式;而是为每个元素生成的 ID 字符串的一维列表。
A.3.1. ID 字符串格式
文档生成器在生成 ID 字符串时遵循下列规则:
· 不在字符串中放置空白。
· 字符串的第一部分通过单个字符后跟一个冒号来标识被标识成员的种类。定义以下几种成员:
字符
说明
E
事件
F
字段
M
方法(包括构造函数、析构函数和运算符)
N
命名空间
P
属性(包括索引器)
T
类型(如类、委托、枚举、接口和结构)
!
错误字符串;字符串的其他部分提供有关错误的信息。例如,文档生成器对无法解析的链接生成错误信息。
· 字符串的第二部分是元素的完全限定名,从命名空间的根开始。元素的名称、包含着它的类型和命名空间都以句点分隔。如果项名本身含有句点,则将用 # (U+0023) 字符替换。(这里假定所有元素名中都没有“# (U+0023)”字符。)
· 对于带有参数的方法和属性,接着是用括号括起来的参数列表。对于那些不带参数的方法和属性,则省略括号。多个参数以逗号分隔。每个参数的编码都与 CLI 签名相同,如下所示:参数由其完全限定名来表示。例如,int 变成 System.Int32、string 变成 System.String、object 变成 System.Object 等。具有 out 或 ref 修饰符的参数在其类型名后跟有 @ 符。对于由值传递或通过 params 传递的参数没有特殊表示法。数组参数表示为 [ lowerbound : size , … , lowerbound : size ],其中逗号数量等于秩减去一,而下限和每个维的大小(如果已知)用十进制数表示。如果未指定下限或大小,它将被省略。如果省略了某个特定维的下限及大小,则“:”也将被省略。交错数组由每个级别一个“[]”来表示。指针类型为非 void 的参数用类型名后面跟一个 * 的形式来表示。void 指针用类型名 System.Void 表示。
A.3.2. ID 字符串示例
下列各个示例分别演示一段 C# 代码以及为每个可以含有文档注释的源元素生成的 ID 字符串:
· 类型用它们的完全限定名来表示。
enum Color { Red, Blue, Green }
namespace Acme
{
interface IProcess {...}struct ValueType {...}
class Widget: IProcess
{
public class NestedClass {...}public interface IMenuItem {...}
public delegate void Del(int i);
public enum Direction { North, South, East, West }
}
}"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"· 字段用它们的完全限定名来表示。
namespace Acme
{
struct ValueType
{
private int total;
}class Widget: IProcess
{
public class NestedClass
{
private int value;
}private string message;
private static Color defaultColor;
private const double PI = 3.14159;
protected readonly double monthlyAverage;
private long[] array1;
private Widget[,] array2;
private unsafe int *pCount;
private unsafe float **ppValues;
}
}"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"· 构造函数。
namespace Acme
{
class Widget: IProcess
{
static Widget() {...}public Widget() {...}
public Widget(string s) {...}
}
}"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"· 析构函数。
namespace Acme
{
class Widget: IProcess
{
~Widget() {...}
}
}"M:Acme.Widget.Finalize"
· 方法。
namespace Acme
{
struct ValueType
{
public void M(int i) {...}
}class Widget: IProcess
{
public class NestedClass
{
public void M(int i) {...}
}public static void M0() {...}
public void M1(char c, out float f, ref ValueType v) {...}
public void M2(short[] x1, int[,] x2, long[][] x3) {...}
public void M3(long[][] x3, Widget[][,,] x4) {...}
public unsafe void M4(char *pc, Color **pf) {...}
public unsafe void M5(void *pv, double *[][,] pd) {...}
public void M6(int i, params object[] args) {...}
}
}"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"· 属性和索引器。
namespace Acme
{
class Widget: IProcess
{
public int Width { get {...} set {...} }
public int this[int i] { get {...} set {...} }
public int this[string s, int i] { get {...} set {...} }
}
}"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"· 事件。
namespace Acme
{
class Widget: IProcess
{
public event Del AnEvent;
}
}"E:Acme.Widget.AnEvent"
· 一元运算符。
namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x) {...}
}
}"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
下面列出可使用的一元运算符函数名称的完整集合:op_UnaryPlus、op_UnaryNegation、op_LogicalNot、op_OnesComplement、op_Increment、op_Decrement、op_True 和 op_False。
· 二元运算符。
namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x1, Widget x2) {...}
}
}"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"
下面列出可使用的二元运算符函数名称的完整集合:op_Addition、op_Subtraction、op_Multiply、op_Division、op_Modulus、op_BitwiseAnd、op_BitwiseOr、op_ExclusiveOr、op_LeftShift、op_RightShift、op_Equality、op_Inequality、op_LessThan、op_LessThanOrEqual、op_GreaterThan 和 op_GreaterThanOrEqual。
· 转换运算符具有一个尾随“~”,然后再跟返回类型。
namespace Acme
{
class Widget: IProcess
{
public static explicit operator int(Widget x) {...}
public static implicit operator long(Widget x) {...}
}
}"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"
好了,以上就是关于Sandcastle的使用,相信大家以后都可以用得上,同时也给自己留作备忘。
为了节省大家的时间,我把这一套软件都放到某度网盘了,下载链接如下(永久有效):
链接:https://pan.baidu.com/s/1SElm0dMGUBTqab26Z1aSUw
提取码:y4m1
API文档生成(c# dll)的更多相关文章
- 【开源】AspnetCore 2.0 自动API文档生成组件,支持protobuffer
本文地址 http://www.cnblogs.com/likeli/p/8204054.html 关于 API文档自动生成,用于对APP端的开发帮助文档生成,默认ProtoBuffer传输格式. 本 ...
- Java 的 Api 文档生成工具 JApiDocs 程序文档工具
JApiDocs 详细介绍 简介 JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具.最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs ...
- 推荐开源Api文档生成工具——Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html 非常的方便. 2步生成API文档. 具体信息见官网哟!
- Node与apidoc的邂逅——NodeJS Restful 的API文档生成
作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...
- [aspnetcore.apidoc]一款很不错的api文档生成工具
AspNetCore.ApiDoc 简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api ...
- 【转载】Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景 没有背景.就自己做自己 ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
- 再见丑陋的 SwaggerUI,这款开源的API文档生成神器界面更炫酷,逼格更高!
一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger.Swagger 是一个规范和完整的框架,用于生成.描述.调试和可视化 RESTful 风格的 Web API 服 ...
- 工具:使用过的 API 文档生成工具
背景 2012 年之前几乎没有为代码增加注释,当然,代码的命名也不见得合理(好的代码胜过面面俱到的注释),后来接触过一些开源框架,优秀的框架都有一个特点:文档和示例非常多,在后来的日子里,几乎会强制自 ...
随机推荐
- Java核心反射机制
Java核心反射机制: 基本反射: 反射是一种动态类的处理机制,通过Class类来实现反射机制: Class类的基本信息: Module java.base Package java.lang Cla ...
- MySql:Windows10安装mysql-8.0.18-winx64步骤
步骤: 1. 首先在安装的mysql目录下创建my.ini文件 (深坑)注意:my.ini必须保存为ANSI格式!!! 可以先创建一个my.txt的文件,然后另存为ANSI格式的文件! my.ini内 ...
- bugku SKCTF管理系统
这题hint是sql约束攻击...sql约束攻击其实我没了解过,当时就各种百度,现在总结一下 0x01: sql约束攻击:通常是sql查询语句select * from username= 'lin' ...
- buu 不一样的flag
一.查壳 二.拖入ida,分析 从这里和51到53行的代码,基本判断这是一个迷宫题,并且是5行5列的一个迷宫.我当时感觉到一个奇怪的地方是 第一个,我自己想明白是因为可能是int型,数字占了4个字节, ...
- WPF教程一:创建Hello world来理解XAML的内容及编译
在实际的WPF开发中遇到很多再用Winform写法来写WPF的开发人员,很多时候项目进度延期.出现非必要的BUG等等.大多是因为开发人员虽然是再写WPF. 但是没有好好的学过WPF,就导致无法发挥出W ...
- .NET 6 Preview 6 正式发布: 关注网络开发
微软.NET 团队的项目经理在博客上发布了.NET 6 Preview 6, 在候选发布阶段之前的倒数第二个预览版,也就是8月份还会发布一个Preview 7,9月份开始进入RC,两个候选版本将专注 ...
- 中国剩余定理简析(python实现)
中国剩余定理CRT 正整数m1,m2,...,mk两两互素,对b1,b2,...,bk的同余式组为 \[\begin{cases} x \equiv b_1\; mod \;m_1\\ x \equi ...
- Centos7 安装Oracle11g Express Edition
Centos7 安装Oracle11g Express Edition 下载地址:https://download.oracle.com/otn/linux/oracle11g/xe/ 一.安装相关依 ...
- 微信小程序云开发-数据库-用户更新数据并提交
一.wxml增加input输入框和[更新商品价格]按钮 在商品详情页新增[更新商品价格]按钮,wxml新增部分代码,input绑定事件,用于获取用户输入的内容.按钮绑定事件,用于更新商品价格. 二. ...
- 网络损伤仪WANsim中的时延的不同模型
网络损伤仪WANsim中的3种时延模型 时延指的是报文从网络的一端到达另一端所花费的时间. 网络损伤仪WANsim中为用户提供了3种时延损伤的模型.常量模型.均匀分布.正态分布. 这3种模型按照各自的 ...