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