在C＃使用XML注釋 選擇自 lotusswan 的 Blog
2024-09-05 20:55:46
供稿：網(wǎng)友
菜鳥(niǎo)學(xué)堂：
在c＃使用xml注釋
簡(jiǎn)介
大多數(shù)程序員可能都聽(tīng)說(shuō)過(guò)java自帶的一個(gè)工具javadoc；使用它可以自動(dòng)地為你的代碼生成html文檔。c＃和c＃編譯器也有類似的功能，不過(guò)它生成的是xml，而不是直接生成html。不過(guò)使用xml會(huì)使得文檔更加靈活。
注釋語(yǔ)法
為了使用c＃提供的xml注釋功能，你的注釋?xiě)?yīng)該使用特殊的注釋語(yǔ)法（///）開(kāi)頭。在///之后，你可以使用預(yù)先定義的標(biāo)簽注釋你的代碼，也可以插入你自己定義的標(biāo)簽。你定制的標(biāo)簽將會(huì)在隨后加入到生成的注釋文檔中。
預(yù)定義的標(biāo)簽 用處
<c> 將說(shuō)明中的文本標(biāo)記為代碼
<code> 提供了一種將多行指示為代碼的方法
<example> 指定使用方法或其他庫(kù)成員的示例
<exception> 允許你指定可能發(fā)生的異常類
<include> 允許你引用描述源代碼中類型和成員的另一文件中的注釋, 使用 xml xpath 語(yǔ)法來(lái)描述你的源代碼中的類型和成員。
<list> 向xml注釋文檔中插入一個(gè)列表
<para> 向xml注釋文檔中插入一個(gè)段落
<param> 描述一個(gè)參數(shù)
<paramref> 提供了一種指示一個(gè)詞為參數(shù)的方法
<permission> 允許你將成員的訪問(wèn)許可加入到文檔中
<remarks> 用于添加有關(guān)某個(gè)類型的信息
<returns> 描述返回值
<see> 指定鏈接
<seealso> 指定希望在“請(qǐng)參見(jiàn)”一節(jié)中出現(xiàn)的文本
<summary> 類型或類型成員的通用描述
<value> 描述屬性
例子
下面的例子為我們常見(jiàn)的helloworld控制臺(tái)應(yīng)用程序添加注釋：
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注釋文檔，我們?cè)谡{(diào)用csc編譯源代碼時(shí)使用/doc選項(xiàng)：
csc /doc:helloworld.xml helloworld.cs
生成的結(jié)果文檔如下：
<?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頁(yè)面
你可能會(huì)問(wèn)自己：我應(yīng)該如何才能得到具有良好格式的html頁(yè)面呢？很簡(jiǎn)單，你可以編寫(xiě)自己的xsl來(lái)轉(zhuǎn)換生成的xml注釋文檔，或者使用visual studio.net開(kāi)發(fā)工具。通過(guò)使用vs.net的【工具】菜單中的【生成注釋web頁(yè)】，你可以得到一系列詳細(xì)說(shuō)明你的項(xiàng)目或解決方案的html頁(yè)面。下面就是通過(guò)vs.net生成的注釋helloworld程序的html頁(yè)面快照：
