** C#文档自动化 **

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

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

文档自动化初步：

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

///

1<summary>
2
3/// A method with a string array param. 
4
5/// </summary>

public void Koo(string[] ss) {}

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

///

1<summary>
2
3///  不产生这行 
4
5/// </summary>

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

产生文档的命令

- 命令行： csc /doc: ….xml …..cs ；

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

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

输出文档的类型描述符

字符

描述

---|---

Namespace

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

Field

Property (包括indexers or other indexed properties)

Method (包括constructors和operators)

Event

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

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

1<member name="F:SimpleXML.Class1.h">
2<summary>
3
4An enum field. 
5
6</summary>
7</member>

1<member name="T:SimpleXML.Class1.hType">
2<summary>
3
4An enum type. 
5
6</summary>
7</member>

xml文档标记。

标记

描述

---|---

  1<c>
  2
  3| 
  4
  5指示这行注释标识为  Code   
  6  
  7<code>
  8
  9| 
 10
 11指示多行注释标识为  Code   
 12  
 13<example>
 14
 15| 
 16
 17经常与  <code>连用，用来给出如何使用某些成员的例子。   
 18  
 19<exception>
 20
 21| 
 22
 23指明一个成员会抛出哪些异常，经常与  cref属性连用。   
 24  
 25<include>
 26
 27| 
 28
 29指明注释在哪些文件中，以及位置。   
 30  
 31<list>
 32
 33| 
 34
 35用来定义表头，经常与  <item>连用   
 36  
 37<newpara>
 38
 39| 
 40
 41内部使用，如  <remarks>或<returns>。让用户有机会给注释文本加入其他的结构。   
 42  
 43<param/>
 44
 45| 
 46
 47说明参数的属性，编译器会检查参数的合法性。如果通不过，会在文档中产生  !标识的警告。   
 48  
 49<paramref>
 50
 51| 
 52
 53类似  <param/>。   
 54  
 55<permission>
 56
 57| 
 58
 59标明用于成员的代码存取的安全性。   
 60  
 61<remarks>
 62
 63| 
 64
 65用于描述  class或其它类型的描述性文字，不涉及具体细节（如果是这样，使用<summary>）。   
 66  
 67<returns>
 68
 69| 
 70
 71描述方法或函数的返回值。   
 72  
 73<see>
 74
 75| 
 76
 77指定一个链接。   
 78  
 79<seealso>
 80
 81| 
 82
 83指定要出现在  See Also部分的文本。   
 84  
 85<summary>
 86
 87| 
 88
 89类型的描述性文字。它会被  vs.net内置的IntelliSense使用并显示在对应的类型中。（即在vs.net中击键“.”出现的提示）   
 90  
 91<value>
 92
 93| 
 94
 95描述属性。   
 96  
 97以上标记的属性。 
 98
 99标记 
100
101| 
102
103描述   
104  
105---|---  
106  
107cref 
108
109| 
110
111可用于任何标记来提供一个代码元素的参考。编译器将检查这个代码元素是否存在，如不存在则在文档中用  !标识。   
112  
113name 
114
115| 
116
117用于  <param/>或<paramref>  
118  
119#  标记使用的例子 
120
1211\.  <param/> 标记 
122
123/// <summary>
124
125/// A method with a string array param. 
126
127/// </summary>
128
129/// <param name="ss"/>
130
131public void Koo(string[] ss) {} 
132
1332\.  <returns> 标记 
134
135/// <summary>
136
137/// A nonvoid method. 
138
139/// </summary>
140
141/// <returns>The result of the operation.</returns>
142
143public int Noo() { return 0; } 
144
1453\.  <exception> 标记和  cref  属性： 
146
147/// <summary>
148
149/// <exception cref="System.Exception">
150
151/// Throws a FileIOException when... 
152
153/// </exception>
154
155/// </summary>
156
157public void Foo() {} 
158
1594\.  <c>, <code>,  和  <example> 标记 
160
161/// <summary>
162
163/// <c>Hoo</c> is a method in the <c>Class1</c> class. 
164
165/// </summary>
166
167public void Hoo() {} 
168
169/// <summary>
170
171/// The Joo method. 
172
173/// <example>This example shows how to use Joo: 
174
175/// <code>
176
177/// <newpara></newpara>
178
179/// public static void  Main  () 
180
181/// { 
182
183///  Console.WriteLine(Class1.Joo()); 
184
185/// } 
186
187/// <newpara></newpara>
188
189/// </code>
190
191/// </example>
192
193/// </summary>
194
195public static int Joo() { return 0; } 
196
197&lt;SPAN style="</example></code></c></exception></returns></paramref></value></summary></seealso></see></returns></summary></remarks></permission></paramref></returns></remarks></newpara></item></list></include></exception></code></example></code></c>