.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
欢迎添加我的公众号一起深入探讨技术手艺人的那些事!
如果您觉得本文的内容有趣就扫一下吧!捐赠互勉!
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· AI与.NET技术实操系列:基于图像分类模型对图像进行分类
· go语言实现终端里的倒计时
· 如何编写易于单元测试的代码
· 10年+ .NET Coder 心语,封装的思维:从隐藏、稳定开始理解其本质意义
· .NET Core 中如何实现缓存的预热?
· 分享一个免费、快速、无限量使用的满血 DeepSeek R1 模型,支持深度思考和联网搜索!
· 基于 Docker 搭建 FRP 内网穿透开源项目(很简单哒)
· ollama系列01:轻松3步本地部署deepseek,普通电脑可用
· 25岁的心里话
· 按钮权限的设计及实现