NDoc: Make good use of your XML Comments.

本专题主要介绍Allen Lee在平时的工作和学习中遇到的好的.NET工具,并讲述相关的使用经验。工欲善其事,必先利其器。那么,现在就让我们看看有什么器可以利吧!

1. 喜欢C#的朋友一定见识过C#的XML文档注释(XML Comments),但是我们可能还没有充分利用这一项功能,顶多,我们仅仅把它跟其他类型的注释等同起来,在代码的页面给出一些说明或者代码功能描述,充其量只是新颖一点,正式的代码描述文档工作还是要另外用Word或者什么来处理。慢着!有没有想过这两者可以结合一起?我的意思是,在源代码上面进行注释,然后直接导出到XML,再加上一些处理成为HTML文档?为了说明问题,我写了一个简单的代码:

using System;
using System.Globalization;

namespace MathUtils
{
///

1<summary>   
2/// 提供复数的相关操作服务。   
3/// </summary>

public sealed class Complex
{
///

1<summary>   
2/// 默认构造器,将复数的实部与虚部分别设置为0;   
3/// </summary>

public Complex()
{
_Real = 0;
_Imaginary = 0;
}

///

1<summary>   
2/// 分别将复数的实部与虚部设置为指定的值。   
3/// </summary>

///

1<param name="real"/>

///

1<param name="imaginary"/>

public Complex( int real, int imaginary)
{
_Real = real;
_Imaginary = imaginary;
}

private int _Real;
///

1<summary>   
2/// 复数的实部。   
3/// </summary>

public int Real
{
get
{
return _Real;
}
set
{
_Real = value ;
}
}

private int _Imaginary;
///

1<summary>   
2/// 复数的虚部。   
3/// </summary>

public int Imaginary
{
get
{
return _Imaginary;
}
set
{
_Imaginary = value ;
}
}

///

1<summary>   
2/// 把复数转换为对应的字符串形式。   
3/// </summary>

///

1<returns>   
2/// 返回(X)+(Y)i的形式的字符串。   
3/// </returns>

public override string ToString()
{
return String.Format(CultureInfo.InvariantCulture,
"{0} + {1}i",
_Real,
_Imaginary);
}

}
}

如果你有Visual C# .NET,那么你可以轻松的使用一下的步骤:在解决方案管理器中右键单击该项目图标,选择属性 |?配置属性 | 生成,在[输出]的[XML 文档文件]右边填入目标XML文件的文件名,这里采用Complex.xml。保存设置并关闭该对话框,生成该项目,你将会在项目的根目录中找到这个XML文件。

如果你没有Visual C# .NET,你大可以使用命令行界面以及CSC.exe,只需要在源代码所在的目录的命令提示符下键入csc Complex.cs /doc:Complex.xml[Enter],就可以生成XML注释文件了。下面看看生成的文件:

 1<doc>
 2<assembly>
 3<name>Complex</name>
 4</assembly>
 5<members>
 6<member name="T:MathUtils.Complex">
 7<summary>   
 8提供复数的相关操作服务。   
 9</summary>
10</member>
11<member name="M:MathUtils.Complex.#ctor">
12<summary>   
13默认构造器,将复数的实部与虚部分别设置为0;   
14</summary>
15</member>
16<member name="M:MathUtils.Complex.#ctor(System.Int32,System.Int32)">
17<summary>   
18分别将复数的实部与虚部设置为指定的值。   
19</summary>
20<param name="real"/>
21<param name="imaginary"/>
22</member>
23<member name="M:MathUtils.Complex.ToString">
24<summary>   
25把复数转换为对应的字符串形式。   
26</summary>
27<returns>   
28返回(X)+(Y)i的形式的字符串。   
29</returns>
30</member>
31<member name="P:MathUtils.Complex.Real">
32<summary>   
33复数的实部。   
34</summary>
35</member>
36<member name="P:MathUtils.Complex.Imaginary">
37<summary>   
38复数的虚部。   
39</summary>
40</member>
41</members>
42</doc>

接下来我们怎么利用这个生成的XML呢?很简单使用我们这次介绍的主角——NDoc,先去 http://ndoc.sourceforge.net/ 下载,安装,然后运行NDoc。点击Add添加生成的Dll或者Exe程序集,以及相关的XML文档文件。然后选择Build来生成文档文件,而且生成的文件还可以选择类型。

就这样,我们就生成了一个文档,这里我选择MSDN文档类型:

可以问你一个问题吗?当你看完这篇介绍后,你有没有想过使用这个工具?有多想?能给我一个回复么?(完全没兴趣、感觉无所谓、有机会可以一试、马上去下载一个看看)谢谢!

Allen Lee

See also:

Reflector: Get the secret inside .NET assemblies

Published At
Categories with Web编程
Tagged with
comments powered by Disqus