使用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下载地址为 ...
随机推荐
- mac 比较两个文件
比较两个文件,输出两个文件都有的行,可以 1.使用comm命令 如下例: ------------------->$ cat 1s1.txt line line line line line l ...
- 玩转mongodb(七):索引,速度的引领(全文索引、地理空间索引)
本篇博文主要介绍MongoDB中一些常用的特殊索引类型,主要包括: 用于简单字符串搜索的全文本索引: 用于球体空间(2dsphere)和二维平面(2d)的地理空间索引. 一.全文索引 MongoDB有 ...
- 关于SAN和NAS的区别-转
什么是SAN与NAS By 王文平 发表于 2006-7-10 18:03:53 NAS和SAN字面上相似,并且都是新型数据存储模式,但这二者是完全不同的,针对不同方向的技术. 什么是SAN(St ...
- 基于多层感知机的手写数字识别(Tensorflow实现)
import numpy as np import tensorflow as tf from tensorflow.examples.tutorials.mnist import input_dat ...
- 浅析libuv源码-编译启动
面试的间隙回头复习了一下node,感觉node就像一个胶带,把V8和libuv粘在了一起. V8毫无疑问,负责解析执行JavaScript,相当于语言层面的桥梁:而libuv则是负责操作系统底层功能的 ...
- C# int? 关键字
1.int? 关键字说明 (1).int? 表示一个int类型,且该int类型可空,如果不加?的话,那么int类型的默认值为0,不能赋null值,代码如下: int aa = null; (2).当 ...
- 使用 ajax 异步调用数据
ajax 脚本 <script type="text/javascript" > function show(page) { var xmlhttp; try { xm ...
- arm裸板驱动总结(makefile+lds链接脚本+裸板调试)
在裸板2440中,当我们使用nand启动时,2440会自动将前4k字节复制到内部sram中,如下图所示: 然而此时的SDRAM.nandflash的控制时序等都还没初始化,所以我们就只能使用前0~40 ...
- 通过AOP自定义注解实现日志管理
前言: 通过自定义注解和AOP结合的方式,实现日志的记录功能 大致流程:项目运行->用户操作调用业务处理类->通过自定义的注解(我理解为一个切点)->进入到AOP切面类(在这里可以获 ...
- Romantic(hdu2699+欧几里德)
Romantic Time Limit: 2000/1000 MS (Java/Others) Memory Limit: 32768/32768 K (Java/Others) Total Subm ...