C#文档推荐使用描述一个对象，描述一个对象成员。奇怪的是如果你用Visual Studio .NET IDE在一个类前输入///，他将自动增加，而不是 ，这时你需要手工输入。
经常在C#文档中发现，这个标记用于描述类的成员，包括属性、方法、成员等。
///
/// This XmlDocument based attribute contains the
/// XML documentation for the project.
///
|
也可以很好的描述对象，但是不推荐，xml注释文档推荐使用描述对象。
被用来演示如何使用，例子可以使任何正确的文本文件，但是更多是一小段代码：
///
///
/// // create the class that does translations
/// GiveHelpTransforms ght = new GiveHelpTransforms();
/// // have it load our XML into the SourceXML property
/// ght.LoadXMLFromFile(
/// "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");
///
///
|
如果其中有代码，经常被使用，是将要被支持的一个标记。
处理异常文档。如果多于一个异常会被抛出，你就需要多个。 有一个属性：cref 这个属性值是将被扔出异常的类名。这个类名必须是正确的，因为C#编译器将检查这一项，后面我将具体讨论。
这篇文章的代码将不会扔出任何异常，但是下面有个代码例子，演示如何使用：
///
/// Normally, a discussion on any exceptions thrown would go here.
///
|
用于描述方法、属性的参数。当你在一个方法前面输入/// 他会被自动的插入。有个属性，name 用于记录源代码中参数的名字。
/// The path to the file containing the
/// source XML.
|
类成员访问修饰符是通过 来记录，它的值用来写明访问限制，值不是必需的。值可以是下面几种：public, private, protected等。Scope 是另外一个标记，用于表示是不是static的方法。
有个属性cref。cref 属性的值用来表示调用当前编译环境的一个类成员或者属性，它通常在System.Security.PermissionSet中定义。
跟 相类似，他用来描述方法、属性的返回值。
/// The HTML for a list of types based on the XML
/// documentation.
|
同一个话题中的其他连接。这个标记通常没有值，仅仅有一个cref属性指向需要引用的对象名。这个属性可以是类、成员等等。
XML compiler可以识别这些符号和内容，并把它转为xml文档，我将在稍后讨论这些xml文档文件。
当编译器从代码中提取xml注释的时候，任何使用标识的文件都将被包含入注释，就像这些文件本来就在注释里面一样。因为编译器可以这样提取外部文件为注释，所以你可以把你的注释放到代码文件之外。不过这些注释并不很直观，因此，我从来不使用。但是如果你的注释太长的话，你可以权衡一下。
的几个用于指定外部文件的属性是必需的。file属性的值必须是绝对或相对文件路径，这个文件必须是一个包含xml注释的xml文件；path属性是用于指定xml注释位置的XPath路径。就像下面代码演示的：
///
public class MyExampleClass
{
///
public string MyExampleMethod(string strReturnThis)
{
return strReturnThis;
}
}
|
This is my example class that does nothing.
This method just returns a string.
This is a string parameter that will just be returned.
Just returns the input parameter.
|
图3：MyXMLCommentFile.xml
图3展示了MyXMLCommentFile.xml的代码。注意，我使用XPath指定注释中的位置。 这个文件实际格式是开发人员自己定的，我更倾向于这个文件跟编译器产生的文件格式是一样的。
相关文章
