.net 函數注析

這段寫在函數前面

 /// <summary>

///在這裡寫注析

/// </summary>

<summary> 标記用于對類型或成員的摘要說明。

<summary>description</summary>

其中:

description

對類型或成員的摘要說明。

應用于

所有的類型及成員。

備注

此标記是所有類型及成員最基本的說明，一般的，應為每個公共的、可見的類型/成員書寫 summary 文檔。在 Visual Studio .NET IDE 的智能感覺功能及對象檢視器，還有其他大多數開發工具，都會顯示 summary 資訊。

NDoc 将标記區分為三類: Section 标記，Block 标記，Inline 标記。

Section 标記

Section 标記用于定義不同的代碼文檔的區域。它們都是頂級标記，Block 标記、Inline 标記都應包含在某個 Section 标記的内部。（除非自定義了擴充 XSLT 轉換，否則，在 Section 标記外部的 Block 标記或 Inline 标記都被忽略。）

标記	說明
<event> [NDoc 擴充]	對某個成員可能引發的事件的說明。
<example>	“示例”，幫助類庫使用者了解類型/成員使用方法的示例代碼。
<exception>	對某個成員可以抛出的異常的說明。
<exclude/> [NDoc 擴充]	訓示 NDoc 文檔引擎将被标記的類型/成員排除在代碼文檔之外。 與文檔引擎的“可見性”配置不符的，以 exclude 優先。
<include>	将代碼檔案外部的某 XML 檔案中的一部分包含進代碼檔案來。
<overloads> [NDoc 擴充]	為“重載清單”頁面準備摘要、備注、示例等文檔内容。隻需在重載成員的第一個成員前面書寫此區域即可。 <overloads> 标記有兩種形式: 簡單的形式，直接在 overload 中寫文本，這些文本被處理為“重載清單”頁面的摘要。沒有備注、示例等區域。 複雜的形式，在 overload 内部，包含 summary, remarks, example 等标記分别表示“重載清單”頁面的摘要、備注、示例等。 示例: ///<overloads>This method has two overloads.</overloads> ///<summary>This overload just says hello.</summary> public void SayHello() { ... } ///<summary>This one says hello to someone.</summary> public void SayHello(string toSomeone) { ... }
<param>	成員的參數說明。
<permission>	通路某成員所必需的 .NET Framework 安全性 CodeAccessPermission。
<preliminary> [NDoc 擴充]	将某類型/成員标記為“預釋出”。内部的文本被當作警告文本用紅色顯示，可以包含 ​​<para>​​ 表示多行文本。如果缺少内部文本，則顯示預設的警告文本: “[此文檔為預釋出版本，在未來版本中有可能改變。]”。 如果需要把全部類型/成員都标記為“預釋出”，請使用文檔引擎的 ​​Preliminary​​ 配置項。
<remarks>	“備注”，對 ​​<summary>​​ 的進一步注解。
<returns>	“傳回值”。
<seealso>	向頁面的“請參見”區域添加一個連結。 請不要将此标記包含在 ​​<remarks>​​ 内部，它是一個頂級标記。 兩種可選的文法: ​ ​<seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso>​ ​ ​ ​<seealso cref="System.Data.DataSet">DataSet</seealso>​ ​
<summary>	“摘要”，對類型/成員的摘要說明。
<threadsafety> [NDoc 擴充]	“線程安全”，說明類型在多線程環境中是否安全。 NDoc 提供 static 和 instance 兩個布爾的屬性，可以自動生成像 .NET Framework SDK 類庫文檔中那樣的标準文本。 threadsafety 标記内部可以包含額外的文本，會被顯示到标準文本的下方，說明額外的資訊。例如: /// <summary>The summary description for SafeClass.</summary> /// <threadsafety static="true" instance="true"> /// <para>More information about using this class across thread</para> /// </threadsafety> public class SafeClass() { ... }
<value>	“屬性值”。

Block 标記

Block 标記用于 Section 标記的内部，它們将顯示在單獨的行中。

标記	說明
<code>	多行的代碼塊。
<list>	一個清單或表格。
<note> [NDoc 擴充]	“注意”塊。 例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary.
<para>	表示一個段落。

Inline 标記

Inline 标記可以用于其他 Section 标記或 Block 标記内部，它們将和前後的文本顯示在同一行中。

标記	說明
<c>	将内部文本格式化為代碼樣式，用于表示行文中提到的短小代碼片段。
<paramref>	加入指向方法參數的連結。
<see>	加入指向某個類型/成員或網絡 URL 的連結。 兩種可選的文法: ​ ​<see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see>​ ​ ​ ​<see cref="System.Data.DataSet">DataSet</see>​ ​ ​ ​<see langword="xxx"/>​ ​其中 xxx 可以是 null, sealed, static, abstract 或 virtual。