C#文档自动化

本文主要参考《inside C#》第15章的内容。

熟悉java的程序员都知道，在java中有一种“文档注释”。采用这种注释之后，使用相应的命令，我们就可以得到与代码相关的文档说明。如今，在.net的世界中C#也提供了相同的功能。如果结合相应的工具，它还可以为我们产生漂亮的WEB风格的文档。

文档自动化初步：
       在C#中文档注释对应的符号是：///。但光使用它还是不能为我们产生代码文档，还必须使用特殊的标记才行。这些标记实际上是XML标记，最常用的是< summary >。例如：

/// <summary>

/// A method with a string array param.

/// </summary>

public void Koo(string[] ss) {}

       但是，并不是所有使用文档注释和这些标记的地方编译器都会为我们生成文档，它还会看这些标记是否与一些代码结构相关联。例如：

/// <summary>

/// 不产生这行

/// </summary>

就不产生任何文档。这些代码结构必须是：class, struct, enum, method, property, field, indexer, delegate, 或event.

产生文档的命令
-          命令行：csc /doc: ….xml …..cs；

-          如使用VS.net，则：项目 -> 属性 -> 配置属性 -> 生成 -> 输出 -> xml文档文件(在此填写文件名和路径)；

-          如要生成web注释：工具 ->生成注释 web......。

输出文档的类型描述符
字符
描述

N
Namespace

T
类型：class, interface, struct, enum, delegate

F
Field

P
Property (包括indexers or other indexed properties)

M
Method (包括constructors和operators)

E
Event

!
Error:编译器无法解析这个元素。


       一个输出的文件注释的示例：

<member name="F:SimpleXML.Class1.h">

    <summary>

    An enum field.

    </summary>

</member>

<member name="T:SimpleXML.Class1.hType">

    <summary>

    An enum type.

    </summary>

</member>

xml文档标记。
标记
描述

<c>
指示这行注释标识为Code

<code>
指示多行注释标识为Code

<example>
经常与<code>连用，用来给出如何使用某些成员的例子。

<exception>
指明一个成员会抛出哪些异常，经常与cref属性连用。

<include>
指明注释在哪些文件中，以及位置。

<list>
用来定义表头，经常与<item>连用

<newpara>
内部使用，如<remarks>或<returns>。让用户有机会给注释文本加入其他的结构。

<param>
说明参数的属性，编译器会检查参数的合法性。如果通不过，会在文档中产生!标识的警告。

<paramref>
类似<param>。

<permission>
标明用于成员的代码存取的安全性。

<remarks>
用于描述class或其它类型的描述性文字，不涉及具体细节（如果是这样，使用<summary>）。

<returns>
描述方法或函数的返回值。

<see>
指定一个链接。

<seealso>
指定要出现在See Also部分的文本。

<summary>
类型的描述性文字。它会被vs.net内置的IntelliSense使用并显示在对应的类型中。（即在vs.net中击键“.”出现的提示）

<value>
描述属性。


以上标记的属性。

标记
描述

cref
可用于任何标记来提供一个代码元素的参考。编译器将检查这个代码元素是否存在，如不存在则在文档中用!标识。

name
用于<param>或<paramref>


标记使用的例子
1.         <param>标记

/// <summary>

/// A method with a string array param.

/// </summary>

/// <param name="ss"></param>

public void Koo(string[] ss) {}



2.         <returns>标记

/// <summary>

/// A nonvoid method.

/// </summary>

/// <returns>The result of the operation.</returns>

public int Noo() { return 0; }



3.         <exception>标记和cref 属性：

/// <summary>

/// <exception cref="System.Exception">

/// Throws a FileIOException when...

/// </exception>

/// </summary>

public void Foo() {}



4.         <c>, <code>, 和<example>标记

/// <summary>

/// <c>Hoo</c> is a method in the <c>Class1</c> class.

/// </summary>

public void Hoo() {}



/// <summary>

/// The Joo method.

/// <example>This example shows how to use Joo:

/// <code>

/// <newpara/>

/// public static void Main()

/// {

///     Console.WriteLine(Class1.Joo());

/// }

/// <newpara/>

/// </code>

/// </example>

/// </summary>

public static int Joo() { return 0; }



5.         <include> 标记

语法：

<include file='filename' path='tagpath[@name="id"]' />



/// <include file='supporting.xml' path='MyDocs/MyMembers[@name="Class1"]/*' />

class Class1{

public static void Main() {}

}

supporting.xml

<MyDocs>

    <MyMembers name="Class1">

        <summary>

        The summary for this type.

        </summary>

    </MyMembers>

    <MyMembers name="Class2">

        <summary>

        Another type description.

        </summary>

    </MyMembers>

</MyDocs>



6.         <list>标记

语法：

<list type="bullet" │ "number" │ "table">

    <listheader>

        <term>term</term>

        <description>description</description>

    </listheader>

    <item>

        <term>term</term>

        <description>description</description>

    </item>

</list>



/// <remarks>Here is an example of a bulleted list:

/// <list type="bullet">

/// <item>

/// <description>Item 1.</description>

/// </item>

/// <item>

/// <description>Item 2.</description>

/// </item>

/// </list>

/// </remarks>

static void Main(string[] args) {}



扩充
       由于产生的文档是XML文件，使得我们对它的处理非常方便。如可以定义一个xls来让它产生符合我们需要的文档，如HTML、WORD等等。对于HTML，C#的编译器有内置的支持。我们可以使用标准的HTML标记来扩充它。但由于XML是well-formed的，因此对于一些没有</…>符号的HTML元素则必须作为一个XML有效元素使用。如<br>，对应为<br/>。