文章出處：51tesing論壇 作者：sincky 發(fā)布時(shí)間：2005-12-10
本文主要參考《inside C#》第15章的內容。
熟悉java的程序員都知道，在java中有一種“文檔注釋”。采用這種注釋之后，使用相應的命令，我們就可以得到與代碼相關(guān)的文檔說(shuō)明。如今，在.net的世界中C#也提供了相同的功能。如果結合相應的工具，它還可以為我們產(chǎn)生漂亮的WEB風(fēng)格的文檔。
文檔自動(dòng)化初步：
在C#中文檔注釋對應的符號是：///。但光使用它還是不能為我們產(chǎn)生代碼文檔，還必須使用特殊的標記才行。這些標記實(shí)際上是XML標記，最常用的是< summary >。例如：
/// <summary>
/// A method with a string array param.
/// </summary>
public void Koo(string[] ss) {}
但是，并不是所有使用文檔注釋和這些標記的地方編譯器都會(huì )為我們生成文檔，它還會(huì )看這些標記是否與一些代碼結構相關(guān)聯(lián)。例如：
/// <summary>
/// 不產(chǎn)生這行
/// </summary>
就不產(chǎn)生任何文檔。這些代碼結構必須是：class, struct, enum, method, property, field, indexer, delegate, 或event.
產(chǎn)生文檔的命令
- 命令行：csc /doc: ….xml …..cs；
- 如使用VS.net，則：項目 -> 屬性 -> 配置屬性 -> 生成 -> 輸出 -> xml文檔文件(在此填寫(xiě)文件名和路徑)；
- 如要生成web注釋?zhuān)汗ぞ?->生成注釋 web......。
輸出文檔的類(lèi)型描述符
字符
描述
N
Namespace
T
類(lèi)型：class, interface, struct, enum, delegate
F
Field
P
Property (包括indexers or other indexed properties)
M
Method (包括constructors和operators)
E
Event
!
Error:編譯器無(wú)法解析這個(gè)元素。
一個(gè)輸出的文件注釋的示例：
<member name="F:SimpleXML.Class1.h">
<summary>
An enum field.
</summary>
</member>
<member name="T:SimpleXML.Class1.hType">
<summary>
An enum type.
</summary>
</member>
xml文檔標記。
標記
描述
<c>
指示這行注釋標識為Code
<code>
指示多行注釋標識為Code
<example>
經(jīng)常與<code>連用，用來(lái)給出如何使用某些成員的例子。
<exception>
指明一個(gè)成員會(huì )拋出哪些異常，經(jīng)常與cref屬性連用。
<include>
指明注釋在哪些文件中，以及位置。
<list>
用來(lái)定義表頭，經(jīng)常與<item>連用
<newpara>
內部使用，如<remarks>或<returns>。讓用戶(hù)有機會(huì )給注釋文本加入其他的結構。
<param>
說(shuō)明參數的屬性，編譯器會(huì )檢查參數的合法性。如果通不過(guò)，會(huì )在文檔中產(chǎn)生!標識的警告。
<paramref>
類(lèi)似<param>。
<permission>
標明用于成員的代碼存取的安全性。
<remarks>
用于描述class或其它類(lèi)型的描述性文字，不涉及具體細節（如果是這樣，使用<summary>）。
<returns>
描述方法或函數的返回值。
<see>
指定一個(gè)鏈接。
<seealso>
指定要出現在See Also部分的文本。
<summary>
類(lèi)型的描述性文字。它會(huì )被vs.net內置的IntelliSense使用并顯示在對應的類(lèi)型中。（即在vs.net中擊鍵“.”出現的提示）
<value>
描述屬性。
以上標記的屬性。
標記
描述
cref
可用于任何標記來(lái)提供一個(gè)代碼元素的參考。編譯器將檢查這個(gè)代碼元素是否存在，如不存在則在文檔中用!標識。
name
用于<param>或<paramref>
標記使用的例子
1. <param>標記
/// <summary>
/// A method with a string array param.
/// </summary>
/// <param name="ss"></param>
public void Koo(string[] ss) {}
2. <returns>標記
/// <summary>
/// A nonvoid method.
/// </summary>
/// <returns>The result of the operation.</returns>
public int Noo() { return 0; }
3. <exception>標記和cref 屬性：
/// <summary>
/// <exception cref="System.Exception">
/// Throws a FileIOException when...
/// </exception>
/// </summary>
public void Foo() {}
4. <c>, <code>, 和<example>標記
/// <summary>
/// <c>Hoo</c> is a method in the <c>Class1</c> class.
/// </summary>
public void Hoo() {}
/// <summary>
/// The Joo method.
/// <example>This example shows how to use Joo:
/// <code>
/// <newpara/>
/// public static void Main()
/// {
/// Console.WriteLine(Class1.Joo());
/// }
/// <newpara/>
/// </code>
/// </example>
/// </summary>
public static int Joo() { return 0; }
5. <include> 標記
語(yǔ)法：
<include file='filename' path='tagpath[@name="id"]' />
/// <include file='supporting.xml' path='MyDocs/MyMembers[@name="Class1"]/*' />
class Class1{
public static void Main() {}
}
supporting.xml
<MyDocs>
<MyMembers name="Class1">
<summary>
The summary for this type.
</summary>
</MyMembers>
<MyMembers name="Class2">
<summary>
Another type description.
</summary>
</MyMembers>
</MyDocs>
6. <list>標記
語(yǔ)法：
<list type="bullet" │ "number" │ "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
/// <remarks>Here is an example of a bulleted list:
/// <list type="bullet">
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// </remarks>
static void Main(string[] args) {}
擴充
由于產(chǎn)生的文檔是XML文件，使得我們對它的處理非常方便。如可以定義一個(gè)xls來(lái)讓它產(chǎn)生符合我們需要的文檔，如HTML、WORD等等。對于HTML，C#的編譯器有內置的支持。我們可以使用標準的HTML標記來(lái)擴充它。但由于XML是well-formed的，因此對于一些沒(méi)有</…>符號的HTML元素則必須作為一個(gè)XML有效元素使用。如<br>，對應為<br/>。
