使用Doxygen生成C#帮助文档
本文为作者原创,转载请注明出处:https://www.cnblogs.com/zhaoqingqing/p/3842236.html
一. 什么是Doxygen?#
Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。
因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。
二. 准备软件#
2.1 doxygen#
下载地址:http://www.stack.nl/~dimitri/doxygen/download.html
2.2 graphviz #
官网:http://www.graphviz.org/content/dot-dotexe
注:这个软件不是必需的,如果需要使用更强大的功能比如类继承体系图等则需要安装此软件配置使用,需要安装Java环境
下载地址:http://www.graphviz.org/Download_windows.php
2.3 Microsoft HTML Help Workshop#
chm文件制作工具
三个软件
三. C#注释#
<Summary> 对整体进行概要性描述
<summary>Description</summary>
类、属性(不推荐)、方法等
<para> 跟在Summary之后,对方法所涉及的入口参数进行有效的解释
<param name=username>本参数是用户的帐号</param>
方法的入口参数;
<returns> 对方法的返回值进行解释;
<returns>返回值零代表操作成功,-1代表操作不成功</returns>
方法的返回值;
<remarks> 对一些语句进行备注性描述
<remarks>本类需要调用另外一个User类相关方法</remarks>
类、方法、属性等;
<see> 在生成的文档中产生一个连接到其它描述的超链接;
<see cref=”[member]”/>
可以在其它注释标识符中加入
<seealso> 与上者的区别是本标识符显示超链接在一个文档的尾部的“See Also”区域,而前者在文档之中;
<seealso cref=”[member]”/>
不可以在其它注释标识符中加入
<value> 对一个属性进行概要性解释;
<value>这是一个public属性</value>
属性
<code> 如果需要置入一部分源代码段,可以使用本标识符将其标记出来
<code>
public int add(int a,b)
{
return a+b;
}
</code>
可以在其它注释标识符中加入
<exception> 对程序中可能抛出的异常做解释;
<exception cref=”System.Exception”>抛出的异常情况</exception>
在方法当中如果有抛出异常,如“try…catch结构”时可以使用本标识符做解释
<permission> 对方法的访问权限做一些解释:
<permission cref=”System.Security.PermissionSet”>这是公共方法</permission>
方法,属性
<c> 与<code>标识符基本相同,但本标识符仅用于单行代码;
<c>return a+b;</c>
可以在其它标识符中插入使用;
<example> 举例说明,通常与<code>配套使用;
<example> 以下示例说明如何调用Add方法:
<code>
class MyClass
{
public static int Main()
{
return Add(1+2);
}
}
</code>
</example>
可以在其它标识符中插入;
<paramref> 在其它地方引用一个入口参数
<paramref cref=”a”>请注意,这是一个整型参数</paramref>
四. 配置#
4.1 Doxygen工作目录#
请选择一个已存在的非中文路径的文件夹,如下图:
4.2 Wizard 向导#
4.2.1 Project 项目#
4.2.2 Mode 模式#
4.2.3 Output 输出#
将With search function的钩去掉
plain HTML,为下图一,with navigation panel为下图二
4.2.4 Diagrams 图表#
(Use built-in class diagram generator)将使用内置的生成功能生成每个类的类图,只有一个类是不为生成的。
如果需要更加大的功能比如类继承体系图请选择第三项(Use dot tool from the GraphViz package)需要安GraphViz。
4.3 Export 导出#
4.3.1 Project 项目#
OUTPUT_LANGUAGE选择chinese TAB_SIZE是Tab的长度
4.3.2 Build 构建#
默认是会生成public方法,这里也选择EXTRACT_ALL。它保证输出所有public方法及project方法,EXTRACT_STATIC是生成静态方法。
4.3.3 Input 输入#
Input为输入目录,支持多个目录,我们可以放入项目目录和include目录,下面的Exclude是忽略目录与文件,可自行添加。
4.3.4 Index 索引#
选择ALPHABETICAL_INDEX,类中将有一个组合类型索引项。
生成的索引如下图所示
4.3.5 HTML#
如果你之前选择了(prepare form compressed HTML(.chm))这里抽GENERATE_HTMLHELP项会是选择状态,它下面的CHM_FILE填写你的CHM文档的名字(要加上.chm)。HHC_LOCATION则选择你的HTML Help WorkShop安装目录下的HHC程序,一般会在C:/Program Files (x86)/HTML Help Workshop/hhc.exe。选择TOC_EXPAND会生成左边的树目录。
4.3.6 Dot#
如果你选用内置的生成功能(Use build-in class diagram generator)此时CLASS_DIAGRAMS会是选择状态,而HAV_DOT是未选择状态,如果你选择用GraphViz的dot工具生成(Use dot tool from the GraphViz package)情况则相反,请你选择上CLASS_DIAGRAMS。此时你需要设置下面的DOT_PATH为GraphViz的安装目录,否则将无法生成。
另外以下选项选择则生成对应的图,不选择则不生成。
CLASS_GRAPHS 类图
COLLABORATION_GRAPH 协作图
GROUP_GRAPHS 组图
UML_LOOK 是否UML外观
INCLUDE_GRAPH include
INCLUDED BY GRAPH 被include
CALL_GRAPH 调用
CALLER_GRAPH 被调用
DIRECTORY_GRAPH 目录图
GRAPHICAL_HIERARCHY 继承体系图
五.Run 运行#
配置好后中进入Run选项卡单击 Run Doxygen 即开始生成,等待生成完毕后点击 “Show HTML output”
六.HTML效果图#
七.CHM效果图#
分享一下我的Doxygen配置文件:http://pan.baidu.com/s/1hqh5Clm
八.提醒#
提醒一下,如果是WIN8的操作系统,建议设置dot的兼容性,并以管理员身份运行,否则一直会弹出dot停止运行的警告框
本文版权归作者和博客园共有,欢迎转载,转载之后请务必在文章明显位置标出原文链接和作者,谢谢。
如果本文对您有帮助,请点击【推荐】您的赞赏将鼓励我继续创作!想跟我一起进步么?那就【关注】我吧。
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· 2 本地部署DeepSeek模型构建本地知识库+联网搜索详细步骤