Sandcastle：生成.NET API文档的工具 (帮忙文档)

(1)准备软件

首先需要我们准备如下软件:

SandCastle, 下载地址: http://sandcastle.codeplex.com/releases/view/47665

(2)准备项目文件

准备好程序的dll文件和注释的xml文件.比如本文实例的两个文件:XmlCommentClassDemo.dll 和 XmlCommentClassDemo.XML

注意如果我们的项目关联多个dll,则需要将相关的项目的dll和注释xml文件都准备好.否则的话在帮助文件中将不能点击相关的类.(如果添加了一个类所在的项目dll和xml文件,则此类在chm文件中可以被点击,点击后跳转到此类的说明页面.)

注释的xml文件生成方法: 点击指定项目, 右键属性.  生成 –> 勾选XML文档文件

 

 

(3)打开Sandcastle生成文档.

1) 在右侧Documentation Sources中选择DLL.

2) 点击生成. OK了.

 

备注: Project Properties为一些生成设置

 

 

 

生成文档内容说明

 

       /// <summary>
       /// Datatable转换为Json
       /// </summary>
       /// <param name="table">Datatable对象</param>
       /// <returns>Json字符串</returns>
       /// <example>
       ///   <code lang="cs" source="G:\JsonHelperTest.cs" region="DataTableToJson" title="example1" />
       ///   <code lang="cs" source="G:\JsonHelperTest.cs" region="DataTableToJson" title="example2" />
       ///   <code>
       ///   AAA.GetJosn(dt)
       ///   </code>
       /// </example>

summary 为 API中的 Description
example 为 API中examle, 可以由多个组成. 由子标签<code>组成
方法1 - 引用外部文件(可以不在项目中) :
<code lang="cs" source="G:\JsonHelperTest.cs" region="DataTableToJson" title="example1" />
source: 文件地址. 可以用相对, 也可以用绝对. 相对是以Sandcastle新建的项目目录
region: 文件中使用 #region DataTableToJson 的部分做为example的代码
title: 在Api中Example区域显示的标题

方法2 - 直接法, 直接在当前的方法或类注释中的<code>写入example代码
       ///   <code>
       ///   AAA.GetJosn(dt)
       ///   </code>

 

 

生成API工具二: GhostDoc

使用教程: http://www.cnblogs.com/chencidi/p/3233194.html

 

部分引用: http://www.cnblogs.com/zhangziqiu/archive/2009/01/31/XmlComment-SandCastle-1.html