SDK文档生成
如何为SDK编写专业的用户指南
我在原来的公司上班时，所有的用户手册都有一个Document Team来负责。每次添加一个新的功能或者对功能进行更改，我们都需要开一个Document Bug，然后Document Team会根据描述信息来更新文档，最终给用户提供一个全面、符合当前软件系统的用户指南。现在我们团队也正在开发一个OSGi.NET平台的产品，这种SDK类的产品如果没有一个专业的用户指南就显得很不专业了。这个产品的RC2版本还没有很好的文档，仅是提供一个基于Word的用户指南和一个API的CHM说明书。现在我们正在为这个产品编写专业的用户指南，因此我就把如何使用工具来编写用户指南的过程在这里做一个描述。
1 用户指南效果图
UIOSP是一个基于OSGi.NET的动态模块化平台，通俗一点，就是一个插件平台。目前用户指南已经编写到“如何创建主程序”这一节了。用户指南由两大部分组成：（1）平台使用指南；（2）API说明书。CHM格式的帮助文档如下所示：
当然，你还可以生成HTML的格式，如下：
接下来我将分别介绍如何来编写平台使用指南和API说明书，由于API说明书比较简单，因此，我把API说明书编写介绍放在前面。
2 如何编写用户指南
2.1 工具
这个用户指南是使用Sandcastle和SandcastleBuilder这两个工具来编写的，你可以从http://sandcastle.codeplex.com/和http://shfb.codeplex.com/站点上下载到这两个工具。安装完成后，你可以运行Sandcastle Help File Builder来创建一个帮助文档项目，我在《[产品开发经验总结] 软件产品背后的冰山一角》已经提到这2个工具了。如下图，我新建了一个UIOSP User Guide的项目，在Documentation Sources添加了UIShell.OSGi.dll和UIShell.OSGi.WebExtension.dll两个API Doc Sources。此外，我还创建了一个UserGuide.content的“平台使用指南”目录。最还，更改了一些用户手册的属性，比如HelpFileFormat我指定的是HtmlHelp1和WebSite。
2.2 API说明书编写
API说明书的编写比较简单，它可以根据我们编写的类的注释生成的XML文件自动的创建出来。API说明书编写的步骤如下：
（1）为类添加注释
为类或者方法添加注释的方式很简单，只要以“///”开头，VS IDE就自动给你生成如下格式的注释。不过，它默认的只有Summary、参数和返回值。
2 ///
3 /// </summary>
4 /// <typeparam name="ServiceInterface"></typeparam>
5 /// <param name="serviceInstance"></param>
6 public void AddService < ServiceInterface > ( object serviceInstance)
7 {
8 Framework.AddSystemService( typeof (ServiceInterface), serviceInstance);
9 }
VS IDE的注释还提供了其它的XMl节点，比如Example、Code、Para等，以下是使用这些节点编写的一个API说明，它在说明里面除了简单注释之外，还举了一个使用API的例子。
2 /// 添加一个全局服务。
3 /// </summary>
4 /// <typeparam name="ServiceInterface"> 服务接口。 </typeparam>
5 /// <param name="serviceInstance"> 服务实现。 </param>
6 /// <example>
7 /// <para> 该方法可以在BundleRuntime启动之前添加一个全局服务，从而所有的插件都可以获取并使用。以下是其用法。 </para>
8 /// <code>
9 /// using(BundleRuntime bundleRuntime = new BundleRuntime(@"D:\UIOSP\MyShell\plugins"))
10 /// {
11 /// Console.WriteLine("Enter 'exit' key to exit...");
12 /// // 添加一个全局服务。
13 /// bundleRuntime.AddService <![CDATA[<ILogService> ]]>(new MyLogService());
14 /// bundleRuntime.Start(); // 启动模块插件运行时。
15 /// Console.ReadLine();
16 /// }
17 /// </code>
18 /// </example>
19 public void AddService < ServiceInterface > ( object serviceInstance)
20 {
21 Framework.AddSystemService( typeof (ServiceInterface), serviceInstance);
22 }
当生成API之后，其对应的内容如下图所示。它包含了方法的注释、参数的注释、使用语法、示例。
一般而言，常见的注释XML如下：
2 < code > content </ code > -- 多行代码
3 < para > content </ para > -- 段落
4 < see cref ="member" /> -- 链接
5 < param > -- 参数
6 < seealso cref ="member" /> -- 显示also列表
7 < example > description </ example > -- 示例
8 < exception cref ="System.Exception" > Thrown when... </ exception > -- Exception声明
9 < remarks > description </ remarks > -- 备注
10 < list type ="bullet" | "number" | "table" > -- 列表
11 < listheader >
12 < term > term </ term >
13 < description > description </ description >
14 </ listheader >
15 < item >
16 < term > term </ term >
17 < description > description </ description >
18 </ item >
19 </ list >
（2）更改项目属性生成注释XML文件
这个步骤比较简单，只需要把“XML文档文件”勾上并指定生成目录就可以了。
（3）添加Doc Sources
接着我们可以使用SandcastleBuilder添加Doc Sources，然后添加一个dll就可以了。
（4）设置需要生成的API的类集合
对于一个SDK而言，暴露过多没有意义的API会对用户造成混淆，因此，我们可以通过SandcastleBuilder来设置不需要生成API的命名空间或者类。如下图所示，你可以通过项目的ApiFilter来设置过滤。
2.3 平台使用指南编写
2.3.1 创建平台使用指南的目录
首先点击项目属性右键，添加“New Item”，选择Content Layout，即文档目录。
然后双击Layout文件，在左侧将显示给目录内容，这样，你可以为目录添加一些节点。首先点击“右键”，然后选择“Add Sibling Topic”来添加一个一级节点。
创建完成后，你可以为一级节点通过“Add Child Topic”菜单添加字节点，这样你就可以构建像UIOSP用户指南的目录了。
2.3.2 编写指南文件
在上面描述的，每一级目录都有一个aml文件，这个文件是这级目录的内容。接下来我们需要填充一些内容。以下示例建立了一个具有示例代码、图片的AML文件。
2 < topic id ="73dfeeb5-c3c9-444f-b23d-b7dc24d3cd2f" revisionNumber ="1" >
3 < developerConceptualDocument xmlns ="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink ="http://www.w3.org/1999/xlink" >
4 < introduction >
5 < para > 该小节向您介绍如何创建Movies插件。该插件为整个应用系统提供了“Movie List”页面——Default.aspx和“Create New Movie”页面——CreateNew.aspx。 </ para >
6 </ introduction >
7 < section address ="CreatePlugin" >
8 < title > 创建插件项目 </ title >
9 < content >
10 < para > 添加一个新建项目，项目模板为UIOSP目录下的“ASP.NET Web空白插件”，名为MoviesPlugin，项目目录位于Plugins下。 </ para >
11 </ content >
12 </ section >
13 < section address ="CreateModel" >
14 < title > 创建数据模型 </ title >
15 < content >
16 < para > 添加一个Movie类，这个类定义了这个插件的数据模型，其定义如下。目前该类只是提供了一些模拟的数据。 </ para >
17 < code language ="cs" >
18 <![CDATA[
19 using System;
20 using System.Collections.Generic;
21 using System.Linq;
22 using System.Web;
23 namespace MoviesPlugin.Model
24 {
25 /// <summary>
26 /// Movie实体定义。
27 /// </summary>
28 public partial class Movie
29 {
30 public string Title { get; set; }
31 public DateTime ReleaseDate { get; set; }
32 public string Genre { get; set; }
33 public string Rating { get; set; }
34 public float Price { get; set; }
35 }
36 }
37 ]]>
38 </ code >
39 </ content >
40 </ section >
41 < section address ="CreateCreateNewPage" >
42 < title > 创建CreateNew.aspx </ title >
43 < content >
44 < para > 到目前为止，MoviesPlugin已经创建完毕。接下来我们将创建一个可重用的LogsPlugin插件，并利用它提供的服务来记录Movie记录操作日志。关于目前解决方案的内容，请查看“Step2-MoviesPlugin.zip”文件，创建的MoviesPlugin插件内容如图3-17所示。 </ para >
45 < para >
46 < mediaLink >
47 < caption >< legacyBold > 图3-17 MoviesPlugin插件内容 </ legacyBold ></ caption >
48 < image xlink:href ="3_17_MoviesPluginContentScreen" />
49 </ mediaLink >
50 </ para >
51 </ content >
52 </ section >
53 </ developerConceptualDocument >
54 </ topic >
图片通过以下XML来添加。
<para>
<mediaLink>
<caption><legacyBold>图3-17 MoviesPlugin插件内容</legacyBold></caption>
<image xlink:href="3_17_MoviesPluginContentScreen"/>
</mediaLink>
</para>
代码通过以下XMl来添加。
<code language="cs">
<![CDATA[
using System;
……
]]>
</code>
有关图文并茂、包括示例代码的帮助编写就先简单的介绍到这。：）
出处：http://www.cnblogs.com/baihmpgy/archive/2010/10/18/1854247.html