.Net魔法堂：提取注释生成API文档

一、前言　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

  在多人协作的项目中，除了良好的代码规范外，完整的API文档也相当重要。通过文档我们快速了解系统各模块的实际接口，及其使用场景、使用示例，一定程度上降低沟通成本，和减少后期维护中知识遗失等风险。

  对于.Net，我们可以直接将类、方法等的注释直接转为API文档，极大地减少文档维护的工作量，同时也能反向提高大家的注释质量。

  下面我们使用.Net唯一的注释生成API文档工具——Sandcastle和Sandcastle Help File Builder来实现API文档自动化吧！

 

二、工具　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

  Sandcastle： http://sandcastle.codeplex.com/

  Sandcastle Help File Builder：http://shfb.codeplex.com/

 

三、从注释到API文档　　　　　　　　　　　　　　　　　　　　　　　　

1. 生成XML文档文件

   步骤：1. 在VS中，右击程序集->选择“属性”->选择“生成”页->勾选“XML文档文件”

           2. 编译程序集后，在生成目录下可以找到“程序集名称.XML”文件。

2. 使用SandcastleBuilderGUI.exe生成API文档

安装工具Sandcastle和Sandcastle Help File Builder后，点击SandcastleBuilderGUI.exe即可进入文档生成项目的界面。

　　步骤：1. 配置文档基本信息：点击“Help File”页

　　按照上图，依次配置文档标题，文档名称，文档语言，文档风格。

　　2. 将程序集DLL和XML文件加载到文档生成项目中。

 　　右击“Documentation Sources”，选择“Add Documentation Sources”，然后将程序集DLL和XML添加进来即可。

       3. 生成API文档

　　 点击菜单栏的“Documentation”->“Build Project”即可，此时只需到Sandcastle Help File Builder.exe所在的目录即可找到API文档了。

 

四、总结　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

  上述仅介绍了Sandcastle Help File Builder的部分功能，日后将逐渐补充。

  尊重原创，转载请注明来自：http://www.cnblogs.com/fsjohnhuang/p/3968313.html  ^_^肥仔John

 

五、参考　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

http://guojun2sq.blog.163.com/blog/static/643308612010116394430/

http://www.boyd.cn/info_Show.asp?ArticleID=4945

http://blog.csdn.net/chtnj/article/details/8278342

http://blog.csdn.net/chtnj/article/details/8278360