csharp-docs

C# 文件化最佳做法

• 公開成員應使用 XML 註解進行文件化。
• 建議也對內部成員進行文件化，特別是當它們較複雜或不易自明時。

所有 API 的指導方針

• 使用 <summary> 提供類型或成員功能的簡短一句話描述。摘要應以現在式第三人稱動詞開頭。
• 使用 <remarks> 提供額外資訊，可包含實作細節、使用注意事項或其他相關背景。
• 使用 <see langword> 表示語言特定關鍵字，例如 null、true、false、int、bool 等。
• 使用 <c> 表示行內程式碼片段。
• 使用 <example> 提供成員的使用範例。
  • 使用 <code> 表示程式碼區塊。<code> 標籤應放在 <example> 標籤內。使用 language 屬性指定程式碼範例的語言，例如 <code language="csharp">。
• 使用 <see cref> 在句子中行內參考其他類型或成員。
• 使用 <seealso> 在線上文件的「另請參閱」區段中，以獨立（非句子內）方式參考其他類型或成員。
• 使用 <inheritdoc/> 從基底類別或介面繼承文件。
  • 除非有重大行為變更，此時應記錄差異。

方法

• 使用 <param> 描述方法參數。
  • 描述應為名詞片語，不指定資料型別。
  • 以介紹性冠詞開頭。
  • 若參數為旗標列舉，描述開頭為「A bitwise combination of the enumeration values that specifies...」。
  • 若參數為非旗標列舉，描述開頭為「One of the enumeration values that specifies...」。
  • 若參數為布林值，措辭應為「<see langword="true" /> to ...; otherwise, <see langword="false" />。」。
  • 若參數為「out」參數，措辭應為「When this method returns, contains .... This parameter is treated as uninitialized。」。
• 使用 <paramref> 在文件中參考參數名稱。
• 使用 <typeparam> 描述泛型類型或方法中的型別參數。
• 使用 <typeparamref> 在文件中參考型別參數。
• 使用 <returns> 描述方法傳回的內容。
  • 描述應為名詞片語，不指定資料型別。
  • 以介紹性冠詞開頭。
  • 若傳回型別為布林值，措辭應為「<see langword="true" /> if ...; otherwise, <see langword="false" />。」。

建構函式

• 摘要措辭應為「Initializes a new instance of the <Class> class [or struct]。」。

屬性

• <summary> 應以以下開頭：
  • 「Gets or sets...」適用於讀寫屬性。
  • 「Gets...」適用於唯讀屬性。
  • 「Gets [or sets] a value that indicates whether...」適用於傳回布林值的屬性。
• 使用 <value> 描述屬性的值。
  • 描述應為名詞片語，不指定資料型別。
  • 若屬性有預設值，請以獨立句子加入，例如「The default is <see langword="false" />」。
  • 若值型別為布林值，措辭應為「<see langword="true" /> if ...; otherwise, <see langword="false" />。The default is ...」。

例外狀況

• 使用 <exception cref> 記錄建構函式、屬性、索引子、方法、運算子和事件擲回的例外狀況。
• 記錄成員直接擲回的所有例外狀況。
• 對於巢狀成員擲回的例外狀況，僅記錄使用者最可能遇到的例外狀況。
• 例外狀況的描述說明其擲回的條件。
  • 省略句子開頭的「Thrown if ...」或「If ...」。直接陳述條件，例如「An error occurred when accessing a Message Queuing API。」。