[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

时间:2024-01-01 13:23:51

Sandcastle介绍

在微软推出Sandcastle之前,人们倾向于选择开源的NDoc(.NET代码文档生成器)。NDo可以将 C#.NET 编译生成的程序集和对应的 /doc XML文档,自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档,然而遗憾的是,这个项目由于资金等问题,作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发,NDoc停留在1.3的历史版本,无法完全支持.NET 2.0,将渐渐淡出人们的视野。

Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一个工具,这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(命令行编译时加/doc参数或vs2005设置项目属性得到)得到一个完整的帮助文档,格式可以是Html或CHM甚至是任何自定义的格式。

类库文档形式的代码文档:

Sandcastle生成的输出结果具有以下特点:

类似于MSDN布局的界面。

自动生成索引项、内容项目表、主题块和页面布局,提高一致性和熟悉程度。

自动生成语法宣称部分。

自动生成继承表。

代码彩色化。

提供多种风格和语言选择,终端用户可从中选择自己最喜欢的形式。

msdn里有一段英文指引大家使用Sandcastle,有图为证

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

下载目录:http://www.microsoft.com/en-us/download/details.aspx?id=10526

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

第一步:程序工程设置

生成项目,应注意的是要将项目属性中【生成】选项卡中的XML文档文件选项设置于选中状态,如下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

项目生成后,在bin\degug目录中生成的文件有与DLL文件同名和一个XML文件,如下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

编码注意事项:程序代码必须要有标准的XML注释,具体细节本篇里就不详细介绍了。

第二步 使用Sandcastle生成帮助文件

1、启动该软件,如下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

2、新建一个项目,参见下图

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

3、选择Add Documentation Source将刚刚创建的类库项目添加到项目中,见下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

在弹出的对话框中选择BookLib类库项目,如下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

编译项目,等待一段时间后显示编译完成在Sandcastle项目目录中的Help目录下就生成了我们类库的帮助文档,如下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

OK,我们看一下帮助文档的内容吧,下图:

[置顶] API相关工作过往的总结之Sandcastle简要使用介绍