Sandcastle Help File Builder

       最近我和其它部门配合,给他们提供一个外部服务,既然是提供给别人用的,当然需要告诉别人怎么来用你的服务,这也就是我们常说的技术文档。各组之间传递技术文档的方式有很多种。这里我知道的大概有以下几种：

       第一：口头传递技术文档，也就是没有实质的文档资料，口头说明一下即可，这种情况局限于沟通起来非常方便的开发团队中，例如就坐在一个办公间等等。

       第二：以文本形式，把如何使用的技术点记录下来，这个方法有什么用，那个属性是做什么的等等，这种方式无疑是表述最清楚的，单独的文档中你甚至可以用图的方式教导使用者，但缺点就是维护起来相当麻烦，而且费时。如果哪天服务的实现有了比较大的改变，那更新这个文档就非常麻烦了。

       第三：利用工具，配合.net的注释来自动生成帮忙文件，这里就是本文所提到的Sandcastle Help File Builder了，后面简称为SHFB。它是Sandcastle的一个可视化工具，用户不用记住大量命令来完成文档的编译。它最终可以生成例如chm文件，内容风格可选MSDN，让使用都可以感到非常亲切。

 

      实现SHFB的软件环境：
      首先：需要安装Sandcastle,大家可以去搜索下载最新版本。
      其实：就是chm文件的制作软件HTML Help Workshop。这个最新版本是1.3，有些所没有更新了。这两个软件最个安装在默认路径下，否则在shfb中需要设置这两个参数。

 

      实现步骤：
      第一：把生成帮助的工程的属性做下修改，右键工程，属性，生成，下面的输出框中有一个生成XML文件选项,打勾。文件会把工程中所有类，方法，属性上的注释保存下来。
      第二：启动shfb，然后新建一个工程，名称可以随意指定。这里主要说说几个比较重要的属性设置问题:

      1：Documentation Sources，是需要生成详细注释的工程。如果最外层工程有对其它工程的引用，而且我们希望看到所有引用的类，就需要把所有被引用的工程都添加进来。否则用户点击外层类时，被引用的类上面不会有链接，即我们看不到被引用类的内容。
      2:References:设置一些工程的依赖项。
      3:FrameworkVersion:  选择对应的Framework版本 ，最新版的shfb的默认设置是.net 3.5。
      4:HelpFileFormat :  选择需要生成的文档的格式. 这里选定的格式要在下面对应的地方进行设置。对于不同的格式还需要安装不同的编译工具 Helpe1x(chm)需要安装Microsoft HTML Help,Helper2x(Hxs)需要安装 Hxcomp.
      5:NamespaceSummaries:  选择需要生成的命名空间，直接点击开窗选择。  

      6:Lanugages ：语言,如果文档中有中文，最好选择中文。
      7:CopyrightHref:版权链接,例如http://www.xxx.com/
      8:CopyrightText: 版权文字 ,xx公司所有
      9:HelpTitle: 文档标题
      10:HtmlHelpName:文档生成文件名称
      11:PresentationStyle: 支持vs 2005,Prototype等格式 ，根据自己需要选择
      12: OutputPath:生成路径,即最后chm文件存放位置，当然除了CHM还有些其它文件。
      13:HtmlHelp1xCompilerPath：可以自定义html help的安装路径。
      14:SandcastlePath：可以自定义sandcastel的安装路径。

      到此，我们就可以点击软件窗口上的buile the help file按钮，就可以按预期进行生成文档了。如果没有特殊情况，运行期间不会发生任何错误，我们会成功的在输出目录中发现chm文件，但有些情况还是需要注意一下的：

       第一：在添加Documentation Sources时，不能在路径中包含.h的字样，例如.Hotel.Host\bin这种路径是不合法的，最后hhc软件会报错。

       第二：References项中不能存在重复项。

       如何正常编写注释，来生成详细可用的帮助文档？

       1：类的注释。一般分为summary以及remarks两部分。

代码

     ///   <summary>
     ///  短信上行服务类
     ///   </summary>
     ///   <remarks>
     ///  2010.07.09: 创建. min.jiang  <br/>
     ///  2010.07.09: 开发短信上行服务  <br/>  
     ///   </remarks>
    [ServiceBehavior(InstanceContextMode  =  InstanceContextMode.PerCall,
        ConcurrencyMode  =  ConcurrencyMode.Multiple,
        IncludeExceptionDetailInFaults  =   true )]
     public   class  HotelCommentWcf : IHotelCommentWcf

 

        2：方法的注释。除了类上面的summary,remarks,还可以加上example，在其中的code标签中加上实例代码等等。

代码

         ///   <summary>
         ///  平台邀请用户进行手机点评方法
         ///   </summary>
         ///   <param name="request"> 用户点评信息 </param>
         ///   <returns> 点评处理结果 </returns>
         ///   <remarks>
         ///  会把点评发送结果发送到用户手机中
         ///   </remarks>
         ///   <example>
         ///      <code>
         ///       HotelCommentWcfClient target = new HotelCommentWcfClient();
         ///       Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.HotelCommentRequestInfo request = null; 
         ///       request = new Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.HotelCommentRequestInfo();
         ///       request.HotelOrderLast4 = "3716";
         ///       request.Mobile = "********";
         ///       request.RecommentContent = "aaa";
         ///       Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.ResponseBaseInfo actual;
         ///       actual = target.SMGAndComment(request);
         ///   </code>
         ///   </example>
         public  ResponseBaseInfo SMGAndComment(HotelCommentRequestInfo request)

         3:属性的注释。这个是最简单的，一般有summary块就行了，其中有一个value块，可以针对默认值进行描述。

  

         总结：Sandcastle Help File Builder能够非常好的和VS合作，制作出MSDN风格的帮忙文档，即有效的对项目保存了技术文档又降低了沟通成本。

 

作者：姜敏
出处：http://www.cnblogs.com/aspnet2008/