強(qiáng)烈推薦：C#類庫(kù)生成API 文檔！
一、Sandcastle
這個(gè)是c#類庫(kù)方法根據(jù)注釋生成幫助文檔的工具，我們經(jīng)常會(huì)遇到把DLL或者API提供給別人調(diào)用的情況，通過(guò)在方法中添加注釋，然后再用Sandcastle 來(lái)自動(dòng)生成文檔給調(diào)用者，如下圖：
圖1：這是Sandcastle Help File Builder軟件界面
圖2：這是生成的chm文檔
還可以直接給出示例代碼：
圖3：還可以直接生成網(wǎng)頁(yè)
二、下載安裝
下載地址：
Help File Builder and Tools v2021.4.9.0最新版本
下載鏈接：https://github.com/EWSoftware/SHFB/releases
單純Sandcastle好像是沒(méi)有界面的， 這個(gè)鏈接提供的下載可以包含圖形界面。
注意：如果需要生成chm還需要微軟的 MicrosoftHTMLHelpWorkshop 支持，Sandcastle生成時(shí)會(huì)自動(dòng)去查找MicrosoftHTMLHelpWorkshop 的安裝目錄。
安裝：
安裝很簡(jiǎn)單，兩個(gè)軟件都只需要直接點(diǎn)擊“下一步”即可安裝完成。
三、Sandcastle配置
安裝好軟件后可以根據(jù)自己的需要配置相應(yīng)的參數(shù)。
默認(rèn)情況下dll中所有方法和屬性都會(huì)生成對(duì)應(yīng)文檔，也可以根據(jù)自己需要只把DLL中需要的類或方法生成文檔，可通過(guò)如下圖配置：
在左側(cè)把需要的類或方法勾選就行了：
在使用工具生成文檔前，別忘了在VS中要作簡(jiǎn)單配置，才能生成DLL對(duì)應(yīng)的XML配置文件，vs配置方法如下：
在VS中右鍵項(xiàng)目屬性：
把"XML documentation file:"勾選，當(dāng)編譯時(shí)在生成DLL的同時(shí)還會(huì)生成一個(gè)和dll同名的xml配置文件。
在Sandcastle中右側(cè)窗口右鍵將需要生成文檔的dll和對(duì)應(yīng)的xml添加進(jìn)來(lái)：
點(diǎn)擊工具欄上的
這個(gè)按鈕就可以自動(dòng)生成文檔了。
四、C#注釋規(guī)范
為了生成友好的幫助文檔，注釋規(guī)范自然少不了，以下是關(guān)于C#的注釋規(guī)范以及各參數(shù)的說(shuō)明，注釋越詳細(xì)，生成的文檔可讀性越好：
1、C#注釋標(biāo)記：
大家對(duì)注釋應(yīng)該都不陌生，在方法或者類前面三個(gè)斜杠就自動(dòng)添加了常用的注釋標(biāo)記，如下圖：
但是如果想要得到更加友好的幫助文檔，注釋得花點(diǎn)心思。
如文章開頭所展示的幫助文檔，部分方法的注釋如下：
2、C#注釋標(biāo)記說(shuō)明：
A.2.1
此標(biāo)記提供一種機(jī)制以指示用特殊字體（如用于代碼塊的字體）設(shè)置說(shuō)明中的文本段落。對(duì)于實(shí)際代碼行，請(qǐng)使用 （第 A.2.2 節(jié)）。
語(yǔ)法：text
示例：
/// Class Point models a point in a two-dimensional
/// plane.
public class Point
{
// ...
}
A.2.2
標(biāo)記用于將一行或多行源代碼或程序輸出設(shè)置為某種特殊字體。對(duì)于敘述中較小的代碼段，請(qǐng)使用 （第 A.2.1 節(jié)）。
語(yǔ)法：
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
此標(biāo)記用于在注釋中插入代碼示例，以說(shuō)明如何使用所關(guān)聯(lián)的方法或其他庫(kù)成員。通常，此標(biāo)記是同標(biāo)記 （第 A.2.2 節(jié)）一起使用的。
語(yǔ)法：description
示例：
有關(guān)示例，請(qǐng)參見(jiàn) （第 A.2.2 節(jié)）。
A.2.4
此標(biāo)記提供一種方法以說(shuō)明關(guān)聯(lián)的方法可能引發(fā)的異常。
語(yǔ)法：description
其中cref="member"
成員的名稱。文檔生成器檢查給定成員是否存在，并將 member 轉(zhuǎn)換為文檔文件中的規(guī)范元素名稱。description 對(duì)引發(fā)異常的情況的描述。
示例：
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
此標(biāo)記允許包含來(lái)自源代碼文件外部的 XML 文檔的信息。外部文件必須是符合標(biāo)準(zhǔn)格式的 XML 文檔，還可以將 XPath 表達(dá)式應(yīng)用于該文檔來(lái)指定應(yīng)包含該 XML 文檔中的哪些 XML 文本。然后用從外部文檔中選定的 XML 來(lái)替換 標(biāo)記。
語(yǔ)法：
filename" path="xpath" /
其中file="filename"
外部 XML 文件的文件名。該文件名是相對(duì)于包含 include 標(biāo)記的文件進(jìn)行解釋的（確定其完整路徑名）。
path="xpath"
XPath 表達(dá)式，用于選擇外部 XML 文件中的某些 XML。
示例：
如果源代碼包含了如下聲明：
///"docs.xml" path='extradoc/class[@name="IntList"]/' /
public class IntList { … }
并且外部文件“docs.xml”含有以下內(nèi)容：
"1.0"?
\ "IntList"
Contains a list of integers.
\ "StringList"
Contains a list of integers.
這樣輸出的文檔就與源代碼中包含以下內(nèi)容時(shí)一樣：
///
/// Contains a list of integers.
///
public class IntList { … }
A.2.6
此標(biāo)記用于創(chuàng)建列表或項(xiàng)目表。它可以包含 塊以定義表或定義列表的標(biāo)頭行。（定義表時(shí)，僅需要在標(biāo)頭中為 term 提供一個(gè)項(xiàng)。）
列表中的每一項(xiàng)都用一個(gè) 塊來(lái)描述。創(chuàng)建定義列表時(shí)，必須同時(shí)指定 term 和 description。但是，對(duì)于表、項(xiàng)目符號(hào)列表或編號(hào)列表，僅需要指定 description。
語(yǔ)法：
term
description
term
description
…
term
description
其中
term
要定義的術(shù)語(yǔ)，其定義位于 description 中。
description
是項(xiàng)目符號(hào)列表或編號(hào)列表中的項(xiàng)，或者是 term 的定義。
示例：
public class MyClass
{
/// Here is an example of a bulleted list:
/// Item 1.
/// Item 2.
public static void Main () {
// ...
}
}
A.2.7.
此標(biāo)記用于其他標(biāo)記內(nèi)，如 （第 A.2.11 節(jié)）或 （第 A.2.12 節(jié)），用于將結(jié)構(gòu)添加到文本中。
語(yǔ)法：
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
該標(biāo)記用于描述方法、構(gòu)造函數(shù)或索引器的參數(shù)。
語(yǔ)法：description 其中name參數(shù)名。description參數(shù)的描述。
示例：
/// 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
該標(biāo)記表示某單詞是一個(gè)參數(shù)。這樣，生成文檔文件后經(jīng)適當(dāng)處理，可以用某種獨(dú)特的方法來(lái)格式化該參數(shù)。
語(yǔ)法：
name
其中
name
參數(shù)名。
示例：
/// 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
該標(biāo)記用于將成員的安全性和可訪問(wèn)性記入文檔。
語(yǔ)法：
description
其中
cref="member"
成員的名稱。文檔生成器檢查給定的代碼元素是否存在，并將 member 轉(zhuǎn)換為文檔文件中的規(guī)范化元素名稱。
description
對(duì)成員的訪問(wèn)屬性的說(shuō)明。
示例:
/// Everyone can
/// access this method.
public static void Test() {
// ...
}
A.2.11
該標(biāo)記用于指定類型的概述信息。（使用 （第 A.2.15 節(jié)）描述類型的成員。）
語(yǔ)法
description
其中
description
摘要文本。
示例：
/// Class Point models a point in a
/// two-dimensional plane.
public class Point
{
// ...
}
A.2.12
該標(biāo)記用于描述方法的返回值。
語(yǔ)法：
description
其中
description
返回值的說(shuō)明。
示例：
/// 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
該標(biāo)記用于在文本內(nèi)指定鏈接。使用 （第 A.2.14 節(jié)）指示將在“請(qǐng)參見(jiàn)”部分中出現(xiàn)的 文本。
語(yǔ)法：
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
該標(biāo)記用于生成將列入“請(qǐng)參見(jiàn)”部分的項(xiàng)。使用 （第 A.2.13 節(jié)）指定來(lái)自文本內(nèi)的鏈接。
語(yǔ)法：
member"/
其中
cref="member"
成員的名稱。文檔生成器檢查給定的代碼元素是否存在，并將 member 更改為所生成的文檔文件中的元素名稱。
示例：
/// This method determines whether two Points have the same
/// location.
///
///
public override bool Equals(object o) {
// ...
}
A.2.15
可以用此標(biāo)記描述類型的成員。使用 （第 A.2.11 節(jié)）描述類型本身。
語(yǔ)法：
description
其中
description
關(guān)于成員的摘要描述。
示例：
/// This constructor initializes the new Point to (0,0).
public Point() : this(0,0) {
}
A.2.16
該標(biāo)記用于描述屬性。
語(yǔ)法：
property description
其中
property description
屬性的說(shuō)明。
示例：
/// Property X represents the point's x-coordinate.
public int X
{
get { return x; }
set { x = value; }
}
A.3. 處理文檔文件
文檔生成器為源代碼中每個(gè)附加了“文檔注釋標(biāo)記”的代碼元素生成一個(gè) ID 字符串。該 ID 字符串唯一地標(biāo)識(shí)源元素。文檔查看器利用此 ID 字符串來(lái)標(biāo)識(shí)該文檔所描述的對(duì)應(yīng)的元數(shù)據(jù)/反射項(xiàng)。
文檔文件不是源代碼的層次化表現(xiàn)形式；而是為每個(gè)元素生成的 ID 字符串的一維列表。
A.3.1. ID 字符串格式
文檔生成器在生成 ID 字符串時(shí)遵循下列規(guī)則：
不在字符串中放置空白。
字符串的第一部分通過(guò)單個(gè)字符后跟一個(gè)冒號(hào)來(lái)標(biāo)識(shí)被標(biāo)識(shí)成員的種類。定義以下幾種成員：
字符串的第二部分是元素的完全限定名，從命名空間的根開始。元素的名稱、包含著它的類型和命名空間都以句點(diǎn)分隔。如果項(xiàng)名本身含有句點(diǎn)，則將用 # (U+0023) 字符替換。（這里假定所有元素名中都沒(méi)有“# (U+0023)”字符。）
對(duì)于帶有參數(shù)的方法和屬性，接著是用括號(hào)括起來(lái)的參數(shù)列表。對(duì)于那些不帶參數(shù)的方法和屬性，則省略括號(hào)。多個(gè)參數(shù)以逗號(hào)分隔。每個(gè)參數(shù)的編碼都與 CLI 簽名相同，如下所示：參數(shù)由其完全限定名來(lái)表示。例如，int 變成 System.Int32、string 變成 System.String、object 變成 System.Object 等。具有 out 或 ref 修飾符的參數(shù)在其類型名后跟有 @ 符。對(duì)于由值傳遞或通過(guò) params 傳遞的參數(shù)沒(méi)有特殊表示法。數(shù)組參數(shù)表示為 [ lowerbound : size , … , lowerbound : size ]，其中逗號(hào)數(shù)量等于秩減去一，而下限和每個(gè)維的大?。ㄈ绻阎┯檬M(jìn)制數(shù)表示。如果未指定下限或大小，它將被省略。如果省略了某個(gè)特定維的下限及大小，則“:”也將被省略。交錯(cuò)數(shù)組由每個(gè)級(jí)別一個(gè)“[]”來(lái)表示。指針類型為非 void 的參數(shù)用類型名后面跟一個(gè) *的形式來(lái)表示。void 指針用類型名 System.Void 表示。
A.3.2. ID 字符串示例
下列各個(gè)示例分別演示一段 C# 代碼以及為每個(gè)可以含有文檔注釋的源元素生成的 ID 字符串：
類型用它們的完全限定名來(lái)表示。
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"
字段用它們的完全限定名來(lái)表示。
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"
構(gòu)造函數(shù)。
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)"
析構(gòu)函數(shù)。
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"
一元運(yùn)算符。
namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x) {...}
}
}
"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
下面列出可使用的一元運(yùn)算符函數(shù)名稱的完整集合：op_UnaryPlus、op_UnaryNegation、op_LogicalNot、op_OnesComplement、op_Increment、op_Decrement、op_True 和 op_False。
二元運(yùn)算符。
namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x1, Widget x2) {...}
}
}
"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"
下面列出可使用的二元運(yùn)算符函數(shù)名稱的完整集合：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。
轉(zhuǎn)換運(yùn)算符具有一個(gè)尾隨“~”，然后再跟返回類型。
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"
好了，以上就是關(guān)于Sandcastle的使用，相信大家以后都可以用得上，同時(shí)也給自己留作備忘。
轉(zhuǎn)自：Alen Liu
鏈接：cnblogs.com/Alenliu/p/15140751.html