一、Sandcastle

這個是c#類庫方法根據(jù)注釋生成幫助文檔的工具，我們經(jīng)常會遇到把DLL或者API提供給別人調(diào)用的情況，通過在方法中添加注釋，然后再用Sandcastle 來自動生成文檔給調(diào)用者，如下圖：

圖1：這是Sandcastle Help File Builder軟件界面

圖2：這是生成的chm文檔

還可以直接給出示例代碼：

圖3：還可以直接生成網(wǎng)頁

二、下載安裝

下載地址：

Help File Builder and Tools v2021.4.9.0最新版本

下載鏈接：https://github.com/EWSoftware/SHFB/releases

單純Sandcastle好像是沒有界面的， 這個鏈接提供的下載可以包含圖形界面。

注意：如果需要生成chm還需要微軟的 MicrosoftHTMLHelpWorkshop 支持，Sandcastle生成時會自動去查找MicrosoftHTMLHelpWorkshop 的安裝目錄。

安裝：

安裝很簡單，兩個軟件都只需要直接點(diǎn)擊“下一步”即可安裝完成。

三、Sandcastle配置

安裝好軟件后可以根據(jù)自己的需要配置相應(yīng)的參數(shù)。

默認(rèn)情況下dll中所有方法和屬性都會生成對應(yīng)文檔，也可以根據(jù)自己需要只把DLL中需要的類或方法生成文檔，可通過如下圖配置：

在左側(cè)把需要的類或方法勾選就行了：

在使用工具生成文檔前，別忘了在VS中要作簡單配置，才能生成DLL對應(yīng)的XML配置文件，vs配置方法如下：

在VS中右鍵項目屬性：

把"XML documentation file:"勾選，當(dāng)編譯時在生成DLL的同時還會生成一個和dll同名的xml配置文件。

在Sandcastle中右側(cè)窗口右鍵將需要生成文檔的dll和對應(yīng)的xml添加進(jìn)來：

點(diǎn)擊工具欄上的

這個按鈕就可以自動生成文檔了。

四、C#注釋規(guī)范

為了生成友好的幫助文檔，注釋規(guī)范自然少不了，以下是關(guān)于C#的注釋規(guī)范以及各參數(shù)的說明，注釋越詳細(xì)，生成的文檔可讀性越好：

1、C#注釋標(biāo)記：

大家對注釋應(yīng)該都不陌生，在方法或者類前面三個斜杠就自動添加了常用的注釋標(biāo)記，如下圖：

但是如果想要得到更加友好的幫助文檔，注釋得花點(diǎn)心思。

如文章開頭所展示的幫助文檔，部分方法的注釋如下：

2、C#注釋標(biāo)記說明：

A.2.1

此標(biāo)記提供一種機(jī)制以指示用特殊字體（如用于代碼塊的字體）設(shè)置說明中的文本段落。對于實際代碼行，請使用 （第 A.2.2 節(jié)）。

語法：text

示例：

/// Class Point models a point in a two-dimensional
/// plane.
public class Point
{
 // ...
}

A.2.2

標(biāo)記用于將一行或多行源代碼或程序輸出設(shè)置為某種特殊字體。對于敘述中較小的代碼段，請使用 （第 A.2.1 節(jié)）。

語法：

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)記用于在注釋中插入代碼示例，以說明如何使用所關(guān)聯(lián)的方法或其他庫成員。通常，此標(biāo)記是同標(biāo)記 （第 A.2.2 節(jié)）一起使用的。

語法：description

示例：

有關(guān)示例，請參見 （第 A.2.2 節(jié)）。

A.2.4

此標(biāo)記提供一種方法以說明關(guān)聯(lián)的方法可能引發(fā)的異常。

語法：description

其中cref="member"

成員的名稱。文檔生成器檢查給定成員是否存在，并將 member 轉(zhuǎn)換為文檔文件中的規(guī)范元素名稱。description 對引發(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)記允許包含來自源代碼文件外部的 XML 文檔的信息。外部文件必須是符合標(biāo)準(zhǔn)格式的 XML 文檔，還可以將 XPath 表達(dá)式應(yīng)用于該文檔來指定應(yīng)包含該 XML 文檔中的哪些 XML 文本。然后用從外部文檔中選定的 XML 來替換 標(biāo)記。

語法：

filename" path="xpath" /

其中file="filename"

外部 XML 文件的文件名。該文件名是相對于包含 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)容時一樣：

 ///
 ///  Contains a list of integers.
 ///
 public class IntList { … }

A.2.6

此標(biāo)記用于創(chuàng)建列表或項目表。它可以包含 塊以定義表或定義列表的標(biāo)頭行。（定義表時，僅需要在標(biāo)頭中為 term 提供一個項。）

列表中的每一項都用一個 塊來描述。創(chuàng)建定義列表時，必須同時指定 term 和 description。但是，對于表、項目符號列表或編號列表，僅需要指定 description。

語法：

term
description


term
description

…

term
description

其中

term

要定義的術(shù)語，其定義位于 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.

此標(biāo)記用于其他標(biāo)記內(nèi)，如 （第 A.2.11 節(jié)）或 （第 A.2.12 節(jié)），用于將結(jié)構(gòu)添加到文本中。

語法：

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ù)。

語法：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)記表示某單詞是一個參數(shù)。這樣，生成文檔文件后經(jīng)適當(dāng)處理，可以用某種獨(dú)特的方法來格式化該參數(shù)。

語法：

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)記用于將成員的安全性和可訪問性記入文檔。

語法：

description

其中

cref="member"

成員的名稱。文檔生成器檢查給定的代碼元素是否存在，并將 member 轉(zhuǎn)換為文檔文件中的規(guī)范化元素名稱。

description

對成員的訪問屬性的說明。

示例:

 /// Everyone can
 /// access this method.

 public static void Test() {
 // ...
 }

A.2.11

該標(biāo)記用于指定類型的概述信息。（使用 （第 A.2.15 節(jié)）描述類型的成員。）

語法

description

其中

description

摘要文本。

示例：

 /// Class Point models a point in a
 /// two-dimensional plane.
 public class Point
 {
 // ...
 }

A.2.12

該標(biāo)記用于描述方法的返回值。

語法：

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

該標(biāo)記用于在文本內(nèi)指定鏈接。使用 （第 A.2.14 節(jié)）指示將在“請參見”部分中出現(xiàn)的 文本。

語法：

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)記用于生成將列入“請參見”部分的項。使用 （第 A.2.13 節(jié)）指定來自文本內(nèi)的鏈接。

語法：

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é)）描述類型本身。

語法：

description

其中

description

關(guān)于成員的摘要描述。

示例：

 /// This constructor initializes the new Point to (0,0).
 public Point() : this(0,0) {
 }

A.2.16

該標(biāo)記用于描述屬性。

語法：

property description

其中

property description

屬性的說明。

示例：

 /// Property X represents the point's x-coordinate.
 public int X
 {
 get { return x; }
 set { x = value; }
 }

A.3.  處理文檔文件

文檔生成器為源代碼中每個附加了“文檔注釋標(biāo)記”的代碼元素生成一個 ID 字符串。該 ID 字符串唯一地標(biāo)識源元素。文檔查看器利用此 ID 字符串來標(biāo)識該文檔所描述的對應(yīng)的元數(shù)據(jù)/反射項。

文檔文件不是源代碼的層次化表現(xiàn)形式；而是為每個元素生成的 ID 字符串的一維列表。

A.3.1.  ID 字符串格式

文檔生成器在生成 ID 字符串時遵循下列規(guī)則：

不在字符串中放置空白。

字符串的第一部分通過單個字符后跟一個冒號來標(biāo)識被標(biāo)識成員的種類。定義以下幾種成員：

字符串的第二部分是元素的完全限定名，從命名空間的根開始。元素的名稱、包含著它的類型和命名空間都以句點(diǎn)分隔。如果項名本身含有句點(diǎn)，則將用 # (U+0023) 字符替換。（這里假定所有元素名中都沒有“# (U+0023)”字符。）

對于帶有參數(shù)的方法和屬性，接著是用括號括起來的參數(shù)列表。對于那些不帶參數(shù)的方法和屬性，則省略括號。多個參數(shù)以逗號分隔。每個參數(shù)的編碼都與 CLI 簽名相同，如下所示：參數(shù)由其完全限定名來表示。例如，int 變成 System.Int32、string 變成 System.String、object 變成 System.Object 等。具有 out 或 ref 修飾符的參數(shù)在其類型名后跟有 @ 符。對于由值傳遞或通過 params 傳遞的參數(shù)沒有特殊表示法。數(shù)組參數(shù)表示為 [ lowerbound : size , … , lowerbound : size ]，其中逗號數(shù)量等于秩減去一，而下限和每個維的大?。ㄈ绻阎┯檬M(jìn)制數(shù)表示。如果未指定下限或大小，它將被省略。如果省略了某個特定維的下限及大小，則“:”也將被省略。交錯數(shù)組由每個級別一個“[]”來表示。指針類型為非 void 的參數(shù)用類型名后面跟一個 *的形式來表示。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"

構(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)算符具有一個尾隨“~”，然后再跟返回類型。

 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的使用，相信大家以后都可以用得上，同時也給自己留作備忘。