把Visual Studio .NET IDE备注信息转换成帮助文档
使用.NET中的XML注释(一)
一.摘要
.Net允许开发人员在源代码中插入XML注释，这在多人协作开发的时候显得特别有用。 C#解析器可以把代码文件中的这些XML标记提取出来，并作进一步的处理为外部文档。这篇文章将展示如何使用这些XML注释。在项目开发中，很多人并不乐意写繁杂的文档。但是，开发组长希望代码注释尽可能详细；项目规划人员希望代码设计文档尽可能详尽；测试、检查人员希望功能说明书尽可能详细等等。如果这些文档都被要求写的话，保持它们同步比进行一个战役还痛苦。
为何不把这些信息保存在一个地方呢？？最明显想到的地方就是代码的注释中；但是你很难通览程序，并且有些需要这些文档的人并不懂编码。最好的办法是通过使用XML注释来解决这些问题。代码注释、用户手册、开发人员手册、测试计划等很多文档可以很方便的从XML注释中获得。本文讲解.Net中经常使用的XML注释.主要使用C#语言j,.Net平台支持的其他语言使用的XML注释格式基本相同.并且在本系列文章的下一讲中讲解如何使用工具将XML注释内容转化为帮助文档.
二.XML注释概述
所有的XML注释都在三个向前的斜线之后(///)。两条斜线表示是一个注释，编译器将忽略后面的内容。三条斜线告诉编译器，后面是XML注释，需要适当地处理。
当开发人员输入三个向前的斜线后，Microsoft Visual Studio .NET IDE 自动检查它是否在类或者类成员的定义的前面。如果是的话，Visual Studio .NET IDE 将自动插入注释标记，开发人员只需要增加些额外的标记和值。下面就是在成员函数前增加三个斜线，自动增加的注释比如:
/// <summary>
/// get hotel info
/// </summary>
/// <param name="hotelId">hotel Id</param>
/// <param name="languageCode">languagecode(Chinese:zh-cn)</param>
/// <returns>hotel info</returns>
[OperationContract]
OutHotelInfo GetHotelInfoByHotelId(string loginName,string loginPassword, string hotelId, string languageCode);
这里嵌入的summary,param,returns标记仅仅是Visual Studio能够识别的一部分标记，然而在智能感知IntelliSense中，并没有把c#规范中所有的标记列出来，遗失的部分只能用手工插入。这些手工标记是非常有用的，如果恰当地设置他们，对导出成外部说明文件将非常有帮助。
三.将注释生成XML文件
在代码中添加的注释信息, 可以单独提取出来, 生成XML文件. 在制作最后的帮助文件的时候会使用到这些注释XML文件.
默认情况下是不生成注释XML文件的.每个项目可以生成一个XML文件,需要我们在项目属性中进行设置:
如上图所示,在项目的"属性页"->"生成"中, 勾选"XML文档文件"复选框,即可在编译时生成注释XML文件.生成路径默认是和dll文件在同一个文件夹下,也可以自行修改.注意此处填写的是相对路径.
四.常见注释标签列表
注释的使用很简单,但是我们使用到的注释很少.这是因为大部分项目中注释的作用仅仅是给程序员自己看.如果想要生成类似MSDN这样的文档,我们需要了解更多的注释标签.下面是我整理的常用的注释标签:
| 标签名称 | 说明 | 语法 | 参数 |
| <summary> | <summary> 标记应当用于描述类型或类型成员。使用 <remarks> 添加针对某个类型说明的补充信息。 <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在 对象浏览器 中。 | <summary> Description </summary> | description:对象的摘要。 |
| <remarks> | 使用 <remarks> 标记添加有关类型的信息，以此补充用 <summary> 指定的信息。此信息显示在对象浏览器中。 | <remarks> Description </remarks> | description:成员的说明。 |
| <param> | <param> 标记应当用于方法声明的注释中，以描述方法的一个参数。 有关 <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。 | <param name='name'> description </param> | name:方法参数名。将此名称用双引号括起来 (" ")。 description:参数说明。 |
| <returns> | <returns> 标记应当用于方法声明的注释，以描述返回值。 | <returns> Description </returns> | description:返回值的说明。 |
| <value> | <value> 标记使您得以描述属性所代表的值。请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary> 标记。然后，应该手动添加 <value> 标记以描述该属性所表示的值。 | <value> property-description </value> | property-description:属性的说明 |
| <example> | 使用 <example> 标记可以指定使用方法或其他库成员的示例。这通常涉及使用 <code> 标记。 | <example> Description </example> | description: 代码示例的说明。 |
| <c> | <c> 标记为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码。 | <c> Text </c> | text :希望将其指示为代码的文本。 |
| <code> | 使用 <code> 标记将多行指示为代码。使用<c>指示应将说明中的文本标记为代码。 | <code> Content </code> | content:希望将其标记为代码的文本。 |
| <exception> | <exception> 标记使您可以指定哪些异常可被引发。此标记可用在方法、属性、事件和索引器的定义中。 | <exception cref="member"> Description </exception> | cref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 有关如何创建对泛型类型的 cref 引用的更多信息，请参见 <see> description:异常的说明。 |
| <see> <seealso> | <see> 标记使您得以从文本内指定链接。使用 <seealso> 指示文本应该放在“另请参见”节中。 | <see cref="member"/> | cref: 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在，并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 (" ") 中。 |
| <para> | <para> 标记用于诸如<summary>，<remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。 | <para>content</para> | content:段落文本。 |
| <code>* | 提供了一种插入代码的方法。 | <code src="src" language="lan" encoding="c"/> | src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码 |
| <img>* | 用以在文档中插入图片 | <img src="src"/> | src:图片的位置，相对于注释所在的XML文件 |
| <file>* | 用以在文档中插入文件，在页面中表现为下载链接 | <file src="src"/> | src:文件的位置，相对于注释所在的XML文件 |
| <localize>* | 提供一种注释本地化的方法，名称与当前线程语言不同的子节点将被忽略 | <localize> <zh-CHS>中文</zh-CHS> <en>English</en> ... </localize> |
|
五.注释与帮助文档
完善注释信息的最终目的就是为了生成MSDN一样的程序帮助文档,此文档将在项目整个生命周期中被各种角色使用:开发人员通过此文档维护程序, 测试人员通过此文档了解业务逻辑, 项目管理人员将此文档用作项目说明等等.
所以要了解列表中这些不常见的注释究竟有何作用,就要和最终的帮助文档关联起来.下面通过示例讲解注释标签在帮助文件中的作用.有关如何生成帮助文件,将在本系列下一篇文章中讲解.
先简单看一下帮助文件的样子.我们都看过MSDN帮助文档,使用注释XML文件生成的帮助文件后缀名是chm,打开后和MSDN基本一样:
本示例的命名空间是XmlCommentClassDemo, 其中包含两个类:
UserBL是包含方法的类.
UserInfo是一个模型类.里面只有UserId和UserName两个属性.
(1)类注释看一下UserBL类的注释代码:
/// <summary>
/// 用户对象业务逻辑层.
/// </summary>
/// <remarks>
/// 2009.01.01: 创建. ziqiu.zhang <br/>
/// 2009.01.23: 增加GetUserName和GetUserId方法. ziqiu.zhang <br/>
/// </remarks>
public class UserBL{...}
Summary标签的内容在命名空间类列表中显示,如上图.remarks标签的内容则显示在类页面中,如下图:
对比以前的注释规范,下面的注释是我们规定在创建一个新的文件时需要添加到头部的注释:
/***************************************************************************************
* *
* *File Name: HotelCommentHeaderInfo.cs
* *Creator: ziqiu.zhang
* *Create Time: 2008-09-17
* *Functional Description: 酒店的点评头模型。包括酒店实体对应的点评头，酒店的OutHotelInfo信息
* ，酒店实体的Tag信息集合。
* *Remark:
* *
* *Copyright (c) eLong Corporation.All rights reserved.
****************************************************************************************/
添加此注释块的目的很好.但是很难推广.因为这段注释并不能被编译器识别,也无法添加到注释XML文件中用于生成帮助文件. 格式不容易记忆,想添加的时候只能从别的复制过来后修改.公司缺少完善的Code Review机制所以最后很多文件都没有此注释块.
相比较使用.NET自己的注释语言,不仅"敏捷",而且会成为帮助文件中的描述.
(2)方法注释
类的注释比较简单.为了样式常用注释标签的效果, 我在方法的注释中使用了尽可能多的注释标签.代码如下:
/// <summary>
///根据用户Id得到用户名.
/// <para>
/// 此处添加第二段Summary信息,在MSDN中很少使用.所以不推荐使用.
/// </para>
/// </summary>
/// <remarks>
///如果没有找到用户则返回null.<br/>
/// <paramref name="userId"/> 参数为正整数.<br/>
///用户Id模型属性定义参见<see cref="UserInfo.UserId"/><br/>
///相关方法:<seealso cref="UserBL.GetUserId"/>
/// </remarks>
/// <param name="userId">用户Id</param>
/// <returns>用户真实姓名</returns>
/// <example>
///返回用户id为100的用户真实姓名:
/// <code>
/// private string userName = string.Empty;
/// userName = UserBL.GetUserName(100);
/// </code>
///返回的用户名可能为null,使用时要先判断:<br/>
/// <c>if(userName!=null){...}</c>
/// </example>
/// <exceptioncref="System.ApplicationException">
///如果用户Id小于0则抛出此异常
/// </exception>
public static string GetUserName(long userId)
{
string result = string.Empty;
if (userId < 0)
{
throw new System.ApplicationException();
}
else if (userId == 0)
{
result = null;
}
else
{
result = "Robert";
}
return result;
}
接下来通过图片进行详细讲解.首先是查看类成员时的截图:
点击方法后的截图:
需要注意的几点:
1) 最开始seealso标签添加在了remarks标签中,所以在See Also区域没有添加上方法的连接. 解决方法是把seealso标签放在summary标签中.
2) 异常类的cref属性需要设置成编译器可以识别的类, 这样才可以在帮助文档中点击.比如上面的System.ApplicationException异常点击后进入微软的在线MSDN查询.如果是自己定义的异常, 需要此异常类也在你的帮助文件中.一般提供注释XML和依赖DLL即可.
(3) 属性的注释
属性的注释也很简单.和类不同的地方在于属性要使用<value>标签而不是<remarks>进行描述:
private string m_UserName = string.Empty;
/// <summary>
/// 用户真实姓名
/// </summary>
/// <value>用户真实姓名字符串.默认值为空.</value>
public string UserName
{
get { return m_UserName; }
set { m_UserName = value; }
}
效果如图:
六.总结
本文讲解了.NET中的XML注释标签, 以及最后在帮助文档中的作用.
使用.NET中的XML注释(二) -- 创建帮助文档入门篇
一.摘要
在本系列的第一篇文章介绍了.NET中XML注释的用途, 本篇文章将讲解如何使用XML注释生成与MSDN一样的帮助文件.主要介绍NDoc的继承者:SandCastle.
二.背景
要生成帮助文件,很多人会想到NDoc.其实在VS2003中不使用NDoc也一样具有"生成Web文档"的功能.然而很不幸,在升级为VS2005和VS2008后, Visual Studio中的此功能已经取消. 更遗憾的是NDoc这个项目由于资金等问题，作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发，NDoc停留在1.3的历史版本，无法完全支持.NET 2.0，将渐渐淡出人们的视野。
去年我还在使用VS2003.所以生成帮助文档使用了其自带的"生成Web文档"功能, 会自动根据注释生成HTML格式的帮助文档.今天我们公司已经全面升级到了VS2008以及Framework3.5,所以经过一番折腾发现居然找不到以前的这个功能了, 而且NDoc也不支持Framework2.0.
经历了一番周折,我发现了SandCastle这个由微软开发的软件.在此还要感谢微软论坛的版主"周雪峰"为我指点迷津告诉我此软件的存在.
在发布VS2005之前，MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。但是当时编译一次文档就需要十多个小时，使得工具的可用性不强。后来随着版本的不断优化,现在生成一个帮助文档大约只需要3分钟(分钟级别,具体时间要看生成文档的大小).
三.SandCastle简介
在上一篇文章中的帮助文件截图都是使用SandCastle生成的,比如下面的截图:
SandCastle是一个微软发布的工具，它通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。这个工具的源代码可以在CodePlex(https://www.codeplex.com/)下获得。SandCastle 主要特性有：
兼容署名或未署名的注释
支持范型以及.NET 2.0框架
支持所有的.NET语言
支持.NET CompactFramework 项目
简单编译接口和Visual Studio插件
四.SandCastle工作原理
从CodePlex上下载SandCastle的源代码,打开后会找到如下项目:
有关这几个项目的关系可以用下图表示:
上图中各部分的作用:
SandCastle中主要有三个组件：MrefBuilder、Build Assembler和XslTransform。
HTML Help 1.xcompiler(hhc.exe) 或者 Microsoft Help 2.0compiler(hxcomp.exe) 用来生成 .chm 或者 .hxs 文件
Help Viewer 用于查看帮助文件.
MrefBuilder和XslTransform
MrefBuilder使用CCI从程序集中生成输出文件
XslTransform使用上面输出的文件生成 Reflection.xml 文档和Manifest文件.其中Reflection.xml包含所有无表现元素的数据.
BuildAssembler
Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。
HTML HelpCompiler(1.x , 2.0 ) 再利用这些HTML文件生成最终结果。
除了上面介绍的核心的三个组件,还有一些用于生成最终文件的工具.比如 HTML Help Complier这个角色是使用HTML Help Workshop工具完成的.HTML HelpWorkshop并不在SandCastle项目中,需要单独下载.要生成最终的.chm格式的文档,必须安装HTML HelpWorkshop.
我们注意到源代码中有一个ChmBuilder, 它的作用是生成可以供HTML Help Workshop使用的.hhc一类的文件,这些文件都是.chm格式文件的元数据.HTML HelpWorkshop的作用就是根据这些文件生成最终文档.
五.快速上手SandCastle
本篇文章只从我所掌握的知识上,讲解如何快速简单的使用SandCastle.方法可能有些繁琐.要想如鱼得水的使用它现在看来必须要使用第三方开发的SandCastle辅助工具.在本系列以后的文章中我会抽出时间进行研究.
(1)准备软件
首先需要我们准备如下软件:
SandCastle, 下载地址:
http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx
说明:
上面的连接会链接到CodePlex上的SandCastle项目的最新Release版本.其中页面上会有如下图两种下载方式:
请下载SandCastle.msi文件,这里包含我们即将使用的一些比如GUI工具等.而下面的源代码zip中则不包含,从大小也能看出来.知道如何使用SVN和TFS的用户也可以从源代码服务器上获取最新的开发中的SandCastle版本,我获取了其SVN上的版本,获取后也包括全部内容和工具.
HTML HelpWorkshop,下载地址:
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en
(2)准备项目文件
准备好程序的dll文件和注释的xml文件.比如本文实例的两个文件:XmlCommentClassDemo.dll和 XmlCommentClassDemo.XML
注意如果我们的项目关联多个dll,则需要将相关的项目的dll和注释xml文件都准备好.否则的话在帮助文件中将不能点击相关的类.(如果添加了一个类所在的项目dll和xml文件,则此类在chm文件中可以被点击,点击后跳转到此类的说明页面.)
(3)使用GUI生成帮助文件元数据
安装完SandCastle后,会在其generic目录中找到GUI工具:SandcastleGui.exe,运行界面如图:
如上图所示,在Name处输入"XmlCommentDemo"后,点击Build,首先会提示保存一个sproj文件.
默认会在创建文件夹: C:ProgramFilesSandcastleExamplesXmlCommentDemo
经过SandCastle我们已经生成了chm文件的元数据文件,路径保存在:
C:ProgramFilesSandcastleExamplesXmlCommentDemovs2005chm 文件夹中.
(4)使用HTML Help Workshop生成CHM文件
在C:ProgramFilesSandcastleExamplesXmlCommentDemovs2005chm 文件夹中有这三个文件:
XmlCommentDemo.hhc
XmlCommentDemo.hhk
XmlCommentDemo.hhp
运行HTML HelpWorkshop,可以打开XmlCommentDemo.hhp文件.单开文件后,单击"File"->"Compile...",弹出如下图的界面:
单击"Compile",则会在.hhp的目录下生成.chm文件,如下图所示:
XmlCommentDemo.chm就是最终文档.
五.总结
经过本篇文章的介绍将使用.NET注释的XML格式文件和程序的DLL文件,生成类似MSDN的文档.对于注释在帮助文档中的作用,请查看本系列的第一篇文章.
由于研究有限我目前也只能粗略的使用SandCastle,后续文章中将陆续深入的学习SandCastle的使用.希望大家能够一起讨论,一起研究,一起进步.
六.相关资源
微软SandCastle博客: http://blogs.msdn.com/sandcastle/default.aspx
SandCastle项目:http://www.codeplex.com/Sandcastle
CodePlex是微软的开源工程网站，涉及诸多微软最新技术的开源工程，同时你也可以建立并向世界展示自己的开源工程。
CodePlex最活跃的技术工程包括
C#,Sharepoint, ASP.NET, .NET, WPF, Ajax, .NET 2.0, Silverlight, DotNetNuke, XNA,TFS, .NET 3.5, Framework, LINQ, SQL Server, Tools, patterns & practices,Library, game, MOSS, CMS, DNN, powershell, MVC, Visual Studio, wcf, Database,SharePoint 2007, xml, orm, SQL, Controls, winforms, blog, utility, VB.NET,Enterprise Library, watch