在C#使用XML注釋

來源:互聯網
上載者:User
xml

    簡介

    大多數程式員可能都聽說過Java內建的一個工具JavaDoc;使用它可以自動地為你的代碼產生HTML文檔。C#和C#編譯器也有類似的功能,不過它產生的是XML,而不是直接產生HTML。不過使用XML會使得文檔更加靈活。

    注釋文法

    為了使用C#提供的XML注釋功能,你的注釋應該使用特殊的注釋文法(///)開頭。在///之後,你可以使用預先定義的標籤注釋你的代碼,也可以插入你自己定義的標籤。你定製的標籤將會在隨後加入到產生的注釋文檔中。

    預定義的標籤            用處

    <c>                             將說明中的文本標記為代碼

    <code>                       提供了一種將多行指示為代碼的方法

    <example>                  指定使用方法或其他庫成員的樣本

    <exception>         允許你指定可能發生的異常類

    <include>                           允許你引用描述原始碼中類型和成員的另一檔案中的注釋, 使用 XML XPath 文法來描述你的原始碼中的類型和成員。

    <list>                           向XML注釋文檔中插入一個列表

    <para>                        向XML注釋文檔中插入一個段落

    <param>                     描述一個參數

    <paramref>                 提供了一種指示一個詞為參數的方法

    <permission>              允許你將成員的訪問許可加入到文檔中

    <remarks>                  用於添加有關某個類型的資訊

    <returns>                    描述傳回值

    <see>                         指定連結

    <seealso>                   指定希望在“請參見”一節中出現的文本

    <summary>                 類型或類型成員的通用描述

    <value>                描述屬性

    例子

    下面的例子為我們常見的HelloWorld控制台應用程式添加註釋:

using System;

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

            return(0);
        }
    }
}

    為產生XML注釋文檔,我們在調用csc編譯原始碼時使用/doc選項:

csc /doc:HelloWorld.xml helloworld.cs

    產生的結果文檔如下:

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>XMlComment</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

            <param name="args">Command Line Arguments</param>

            <returns>Status code of 0 on successful run</returns>

            </summary>

        </member>

    </members>

</doc>

    HTML頁面

    你可能會問自己:我應該如何才能得到具有良好格式的HTML頁面呢?很簡單,你可以編寫自己的XSL來轉換產生的XML注釋文檔,或者使用Visual Studio.NET開發工具。通過使用VS.NET的【工具】菜單中的【產生注釋web頁】,你可以得到一系列詳細說明你的項目或解決方案的HTML頁面。下面就是通過VS.NET產生的注釋helloWorld程式的HTML頁面快照:



相關文章

Cloud Intelligence Leading the Digital Future

Alibaba Cloud ACtivate Online Conference, Nov. 20th & 21st, 2019 (UTC+08)

Register Now >

Starter Package

SSD Cloud server and data transfer for only $2.50 a month

Get Started >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。