您现在的位置：程式碼之家 >> 編程語言 > >> .NET 網頁程式設計 >> C# >> 關於C#

C# XML 文件註解完整指南：從標籤語法到產生 HTML 文件

編輯：關於C#

前言

C# 編譯器支援從原始碼的 XML 註解產生文件檔，類似 JavaDoc 但輸出為結構化 XML，後續可透過 XSLT 轉換為 HTML、PDF 等格式。本文詳細說明註解語法、標準標籤、編譯選項與 Visual Studio 整合產生網頁文件的流程。

XML 註解語法

使用 /// 三斜線開啟單行 XML 註解。
區塊註解可用 /** ... */（較少見）。
標籤區分大小寫，巢狀需正確閉合。

標準標籤對照表

標籤	用途	範例
`<summary>`	類型/成員摘要描述	`<summary>計算兩數和</summary>`
`<param name="...">`	方法參數說明	`<param name="a">第一個加數</param>`
`<returns>`	回傳值說明	`<returns>兩數之和</returns>`
`<exception cref="...">`	可能拋出的例外	`<exception cref="ArgumentNullException">參數為 null</exception>`
`<example>`	使用範例	`<example>var sum = Add(1,2);</example>`
`<see cref="..."/>`	參考其他成員（產生連結）	`<see cref="Add(int,int)"/>`
`<seealso cref="..."/>`	「另請參閱」區塊	`<seealso cref="Subtract"/>`
`<remarks>`	補充說明	`<remarks>此方法為靜態</remarks>`
`<value>`	屬性值說明	`<value>目前溫度</value>`
`<c>`	行內程式碼標記	`<c>Console.WriteLine</c>`
`<code>`	多行程式碼區塊	`<code>...</code>`
`<list>`	列表（table/bullet/number）	`<list type="bullet">...</list>`
`<para>`	段落分隔	`<para>第一段</para><para>第二段</para>`
`<include>`	引用外部 XML 註解檔	`<include file="comments.xml" path="//Class[@name='Foo']">`
`<permission>`	存取權限描述	`<permission cref="SecurityPermission">...</permission>`
`<paramref name="..."/>`	參數名稱參考（斜體顯示）	`<paramref name="a"/>`

完整範例

using System;

namespace HelloWorld
{
    /// 
    /// Sample Hello World in C#
    /// 
    public class HelloWorld
    {
        /// 
        /// Console Application Entry Point
        /// 
        /// Command Line Arguments
        /// Status code of 0 on successful run
        public static int Main(string[] args)
        {
            System.Console.WriteLine("HelloWorld");
            string name = System.Console.ReadLine();
            return 0;
        }
    }
}

編譯產生 XML 文件

csc /doc:HelloWorld.xml HelloWorld.cs

或在專案屬性 → Build → 勾選 "XML documentation file" 指定輸出路徑。

產生的 XML 結構

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>HelloWorld</name>
  </assembly>
  <members>
    <member name="T:HelloWorld.HelloWorld">
      <summary>Sample Hello World in C#</summary>
    </member>
    <member name="M:HelloWorld.HelloWorld.Main(System.String[])">
      <summary>Console Application Entry Point</summary>
      <param name="args">Command Line Arguments</param>
      <returns>Status code of 0 on successful run</returns>
    </member>
  </members>
</doc>

成員 ID 前綴：T=Type、M=Method、P=Property、F=Field、E=Event、N=Namespace。