使用Doxygen生成C#帮助文档

本文为作者原创,转载请注明出处:https://www.cnblogs.com/zhaoqingqing/p/3842236.html



一. 什么是Doxygen?#

Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。
因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。

二. 准备软件#

2.1 doxygen#

官网:http://www.doxygen.nl/

下载地址:http://www.stack.nl/~dimitri/doxygen/download.html

image

2.2 graphviz #

官网:http://www.graphviz.org/content/dot-dotexe

注:这个软件不是必需的,如果需要使用更强大的功能比如类继承体系图等则需要安装此软件配置使用,需要安装Java环境
下载地址:http://www.graphviz.org/Download_windows.php

image

 

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工作目录#

请选择一个已存在的非中文路径的文件夹,如下图:

image

4.2 Wizard 向导#

      4.2.1 Project 项目#

image

      4.2.2 Mode 模式#

image

 

      4.2.3 Output 输出#

将With search function的钩去掉

image

plain HTML,为下图一,with navigation panel为下图二

image   image

      4.2.4 Diagrams 图表#

image

(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的长度

image

image

      4.3.2 Build 构建#

默认是会生成public方法,这里也选择EXTRACT_ALL。它保证输出所有public方法及project方法,EXTRACT_STATIC是生成静态方法。

 

image

      4.3.3 Input 输入#

Input为输入目录,支持多个目录,我们可以放入项目目录和include目录,下面的Exclude是忽略目录与文件,可自行添加。

image

      4.3.4 Index 索引#

选择ALPHABETICAL_INDEX,类中将有一个组合类型索引项。

image

生成的索引如下图所示

image

      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会生成左边的树目录。

image

      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        继承体系图

image

五.Run 运行#

配置好后中进入Run选项卡单击 Run Doxygen 即开始生成,等待生成完毕后点击 “Show HTML output

image

六.HTML效果图#

 

image 

imageimage

image

七.CHM效果图#

imageimage

分享一下我的Doxygen配置文件:http://pan.baidu.com/s/1hqh5Clm

八.提醒#

提醒一下,如果是WIN8的操作系统,建议设置dot的兼容性,并以管理员身份运行,否则一直会弹出dot停止运行的警告框

image

作者:赵青青   一名在【网易游戏】做游戏开发的程序员,擅长Unity3D,游戏开发,.NET等领域。
本文版权归作者和博客园共有,欢迎转载,转载之后请务必在文章明显位置标出原文链接和作者,谢谢。
如果本文对您有帮助,请点击【推荐】您的赞赏将鼓励我继续创作!想跟我一起进步么?那就【关注】我吧。
posted @   赵青青  阅读(7218)  评论(2编辑  收藏  举报
编辑推荐:
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
阅读排行:
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· 2 本地部署DeepSeek模型构建本地知识库+联网搜索详细步骤
CONTENTS
点击右上角即可分享
微信分享提示