使用Doxygen生成C#帮助文档
一. 什么是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停止运行的警告框
使用Doxygen生成C#帮助文档的更多相关文章
- 使用Doxygen生成net帮助文档
一. 什么是Doxygen? Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件.通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打 ...
- Doxygen生成美丽注释文档(1):初体验
Chapter 1 - 准备工作 (Windows环境) 1.1 程序包下载 1. Doxygen * 源码: git clone https://github.com/doxygen/doxygen ...
- 遇到doxygen生成的chm文档目录如果有中文是乱码?
原因不在于doxygen,它没有问题,问题出在微软的HTML Help Workshop的hhc.exe不支持utf8.所以要解决这个问题,需要做两个额外的步骤: 1.将html/index.hhp中 ...
- 安装doxygen(一个自动文档生成工具)+Graphviz图形可视化软件
参考文章: http://www.fmddlmyy.cn/text21.html http://www.cnblogs.com/duguguiyu/archive/2008/06/29/1231852 ...
- 使用sphinx快速生成Python API 文档
一 简单介绍 不管是开源还是闭源,文档都是很重要的.当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了.所以我们要写文档.大部分情况,我们不希望维护一份代码再加上一份文档, ...
- 【原创】利用doxygen来管理项目文档或注释
一.doxygen应用场景: doxygen可以用来管理目前主流的编程语言的注释而形成文档系统.(包括C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Py ...
- 用doxygen风格注释代码生成文档
目录 用doxygen风格注释代码生成文档 1. 说明 2. 具体操作 2.1 生成头部注释 2.2 安装doxygen 2.3 工程配置 3. 总结 用doxygen风格注释代码生成文档 1. 说明 ...
- 生成iOS-Xcode技术文档
从源码中抽取注释生成文档的专用工具: [doxygen](http://www.stack.nl/~dimitri/doxygen/index.html):适于生成html文档与pdf文档. 支持的语 ...
- 使用 Sandcastle 生成代码帮助文档
使用 Sandcastle可以生成MSDN风格的帮助文档,生成的帮助文档既可以是chm文档,也可以是MS Help 2.x帮助文档. 1 下载并安装Sandcastle Sandcastle下载地址为 ...
随机推荐
- 交换排序:冒泡排序vs快速排序
在开发的过程中, 经常会遇到集合排序, 那么一般情况下, 我们都是使用list.OrderBy()的方式来排序, 也无需关注到里面算法的实现是个什么样子. 正好这几天准备回顾一下数据结构与算法. 首先 ...
- windows10 设置软件开机启动
在 C:\Users\your_name\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup 在这个目录下,新建你想开机启动的软 ...
- Microsoft.Net 版本
Date Framework Visual Studio C# CLR 2002.2 1.0 Visual Studio 2002 1.0 1.0 2003.4 1.1 Visual Studio 2 ...
- Nginx range filter模块数字错误漏洞修复 (Nginx平滑升级)
对线上生产环境服务器进行漏洞扫描, 发现有两台前置机器存在Nginx range filter模块数字错误漏洞, 当使用nginx标准模块时,攻击者可以通过发送包含恶意构造range域的header ...
- 解压cpio.gz、zip类型文件
aix上的oracle介质文件是10gr2_aix5l64_database.cpio.gz 解压方法: gunzip 10gr2_aix5l64_database.cpio.gz cpio -idm ...
- vue---数据更新,视图不更新问题
写点赞功能时,点赞后已经追加到对象里了,但是视图没有更新. 查找了些资料: 数据已经更新了但是视图不更新的问题,有几个原因: 1.根属性不存在,而想要直接给根属性赋值导致的视图不更新.此时初始化属性的 ...
- Repeater控件添加onmouseover和onmouseout事件
网友有问题,在Repeater控件中,需要添加onmouseover和onmouseout事件功能.Insus.NET有叫他参考<onmouseover和onmouseout在Repeater控 ...
- Could not initialize plugin: interface org.mockito.plugins.MockMaker
IDE:Idea 添加依赖 <dependency> <groupId>net.bytebuddy</groupId> <artifactId>byte ...
- Java图片验证码乱码问题
有时部署到linux服务器上的web项目的图形验证码可能会出现乱码问题 这不是编码格式出错了,而是可能服务器上没有图形验证码中限定的那种字体 比如生成图形验证码的代码: Font font = new ...
- ArrayList源码解读(jdk1.8)
概要 上一章,我们学习了Collection的架构.这一章开始,我们对Collection的具体实现类进行讲解:首先,讲解List,而List中ArrayList又最为常用.因此,本章我们讲解Arra ...