使用Doxygen生成C#帮助文档

简介:



一. 什么是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


本文转自赵青青博客园博客,原文链接:http://www.cnblogs.com/zhaoqingqing/p/3842236.html,如需转载请自行联系原作者



相关文章
|
C# Windows
C#编程学习15:应用程序帮助文档(chm/pdf)制作与C#调用
C#编程学习15:应用程序帮助文档(chm/pdf)制作与C#调用
C#编程学习15:应用程序帮助文档(chm/pdf)制作与C#调用
|
XML C# 数据格式
工具分享——将C#文档注释生成.chm帮助文档
原文:工具分享——将C#文档注释生成.chm帮助文档 由于最近需要把以前的一个项目写一个文档,但一时又不知道写成怎样的,又恰好发现了可以生成chm的工具,于是乎我就研究了下,感觉还不错,所以也给大家分享下。
1253 0
|
6月前
|
开发框架 前端开发 .NET
C#编程与Web开发
【4月更文挑战第21天】本文探讨了C#在Web开发中的应用,包括使用ASP.NET框架、MVC模式、Web API和Entity Framework。C#作为.NET框架的主要语言,结合这些工具,能创建动态、高效的Web应用。实际案例涉及企业级应用、电子商务和社交媒体平台。尽管面临竞争和挑战,但C#在Web开发领域的前景将持续拓展。
201 3
|
6月前
|
SQL 开发框架 安全
C#编程与多线程处理
【4月更文挑战第21天】探索C#多线程处理,提升程序性能与响应性。了解C#中的Thread、Task类及Async/Await关键字,掌握线程同步与安全,实践并发计算、网络服务及UI优化。跟随未来发展趋势,利用C#打造高效应用。
199 3
|
18天前
|
C# 开发者
C# 一分钟浅谈:Code Contracts 与契约编程
【10月更文挑战第26天】本文介绍了 C# 中的 Code Contracts,这是一个强大的工具,用于通过契约编程增强代码的健壮性和可维护性。文章从基本概念入手,详细讲解了前置条件、后置条件和对象不变量的使用方法,并通过具体代码示例进行了说明。同时,文章还探讨了常见的问题和易错点,如忘记启用静态检查、过度依赖契约和性能影响,并提供了相应的解决建议。希望读者能通过本文更好地理解和应用 Code Contracts。
30 3
|
1月前
|
安全 C# 数据安全/隐私保护
实现C#编程文件夹加锁保护
【10月更文挑战第16天】本文介绍了两种用 C# 实现文件夹保护的方法:一是通过设置文件系统权限,阻止普通用户访问;二是使用加密技术,对文件夹中的文件进行加密,防止未授权访问。提供了示例代码和使用方法,适用于不同安全需求的场景。
112 0
|
2月前
|
API C#
C# 一分钟浅谈:文件系统编程
在软件开发中,文件系统操作至关重要。本文将带你快速掌握C#中文件系统编程的基础知识,涵盖基本概念、常见问题及解决方法。文章详细介绍了`System.IO`命名空间下的关键类库,并通过示例代码展示了路径处理、异常处理、并发访问等技巧,还提供了异步API和流压缩等高级技巧,帮助你写出更健壮的代码。
42 2
|
2月前
|
安全 程序员 编译器
C#一分钟浅谈:泛型编程基础
在现代软件开发中,泛型编程是一项关键技能,它使开发者能够编写类型安全且可重用的代码。C# 自 2.0 版本起支持泛型编程,本文将从基础概念入手,逐步深入探讨 C# 中的泛型,并通过具体实例帮助理解常见问题及其解决方法。泛型通过类型参数替代具体类型,提高了代码复用性和类型安全性,减少了运行时性能开销。文章详细介绍了如何定义泛型类和方法,并讨论了常见的易错点及解决方案,帮助读者更好地掌握这一技术。
78 11
|
2月前
|
SQL 开发框架 安全
并发集合与任务并行库:C#中的高效编程实践
在现代软件开发中,多核处理器普及使多线程编程成为提升性能的关键。然而,传统同步模型在高并发下易引发死锁等问题。为此,.NET Framework引入了任务并行库(TPL)和并发集合,简化并发编程并增强代码可维护性。并发集合允许多线程安全访问,如`ConcurrentQueue&lt;T&gt;`和`ConcurrentDictionary&lt;TKey, TValue&gt;`,有效避免数据不一致。TPL则通过`Task`类实现异步操作,提高开发效率。正确使用这些工具可显著提升程序性能,但也需注意任务取消和异常处理等常见问题。
48 1