doxygen 命令_使用 Doxygen 制作 C 程序文档
目前,网上所能搜到 Doxygen 资料,大都是介绍 C++ 程序文档生成的,对于 C 程序的文档生成鲜有记述。由于我们的项目主要是采用 C 语言实现,这两天在学习使用 Doxygen 制作 C 程序文档时,摸索了一点东西出来,记之备忘。
关于 Doxygen
我们在写程序时,通常会在源码中适当之处添加合理的注释,以此来说明代码所能实现的功能、使用约定等信息。如果在撰写代码注释时,能够稍微遵从某种格式,然后采用某种工具,根据源码结构及注释自动生成排版美观的文档,这将大大减轻我们的工作量,使我们多一些时间享受生命。 Doxygen 就是这样一种工具。
关于 Doxygen 更为详尽的介绍,请阅读其官方主页。
安装 Doxygen
几乎所有的 GNU/Linux 发行版的软件仓库中都可以找到 Doxygen,有些发行版默认已经安装,安装前请检查一下。
如果你打算在 Windows 环境中使用 Doxygen,我会劝说你删除 Windows -> 安装一个 GNU/Linux -> 安装 Doxygen,如果你非要坚持在 Windows 环境中使用 Doxygen,那我只好告诉你:去 Doxygen 官方网站 下载一个 Win 版本的 Doxygen,然后双击所下载的安装文件,然后 Next … Next …
Doxygen 的工作过程
Doxygen 的工作过程可分为三个步骤:
配置 Doxygen 工作环境,生成 Doxygen 配置文件;
在程序源码中添加符合 Doxygen 可解析的注释格式;
使用 Doxygen 解析源码,输出格式化文档。
在 Doxygen 手册页上可以看到一份很详细的 Doxgen 工作流程图。对于我而言,仅仅需要 Doxygen 完成以下流程即可满足我的需求。
从一个具体而微的示例开始
为了更好的学习 Doxygen,构造了一个很小型的“项目”,为了叙述的方便,给它取个名字——“M2 List”,其内容是我从我们的项目中的双向链表模块抽取出来的。
M2 List 项目的目录结构如下图所示:
m2-list
|---- src
| |
| |---- m2.h
| |---- m2-list.h
| |---- m2-list.c
|
|---- lib
|
|---- doc
|
|---- example
|
|---- test.c
M2 List 程序目录为 m2-list,src 目录用于放置程序源文档,example 用于放置测试程序,lib 用于放置最终生成的 M2 List 共享库文件。
下面讲述如何使用 Doxygen 为 M2 List 项目生成文档。
Step 1: 配置 Doxygen 工作环境
Doxygen 工作环境的配置貌似非常复杂,配置文件中的选项有数百项之多,不过其中的绝大多数不需理会,采用 Doxygen 配置文件模板中定义的默认值即可。
进入 m2-list 目录,使用 "doxygen -g" 命令生成 Doxygen 配置文件模板:
$ cd yourpath/m2-list
$ doxygen -g
默认生成的配置文件名为 "Doxyfile",也可以采用 "doxygen -g your-cfg-filename" 命令格式指定所生成的配置文件名。如无特殊需要,采用默认的配置文件名即可。
Doxyfile 文件内容非常多,大概 1000 多行,不过其中约 4/5 都是注释,每个配置选项都有一段详细的注释。日后,如果对 Doxygen 各配置选项的意义有一定了解,可以在生成配置文件的命令中添加 "-s" 选项,生成不含注释的配置文件,操作如下:
$ doxygen -s -g
为实现本文目的,对默认生成的 Doxygen 配置文件需要有针对性的调整,使之适于 C 程序文档生成。下面给出我认为重要的几个配置选项及相应设置:
# 项目名称,将作为于所生成的程序文档首页标题
PROJECT_NAME = “M2 List”
# 文档版本号,可对应于项目版本号,譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = "1.0.0"
# 程序文档输出目录
OUTPUT_DIRECTORY = doc/
# 程序文档语言环境
OUTPUT_LANGUAGE = Chinese
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
# 在 C++ 程序文档中,该值可以设置为 NO,而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES
HIDE_SCOPE_NAMES = YES
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息
QUIET = YES
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS = *.h
# 递归遍历当前目录的子目录,寻找被文档化的程序源文件
RECURSIVE = YES
# 示例程序目录
EXAMPLE_PATH = example/
# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象
EXAMPLE_PATTERNS = *.c \
*.h
# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件
EXAMPLE_RECURSIVE = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
# 不生成 latex 格式的程序文档
GENERATE_LATEX = NO
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
可以下载我的配置文档作为参考: My Doxyfile。
欲详知 Doxygen 各配置选项的作用,请阅读 doxygen 手册中的 config.html 页面 (通常位于 /usr/share/doc/doxygen*/html/config.html)。
Step 2: 程序源码文档化
准备好 Doxygen 的工作环境后,就需要根据 Doxygen 所定义的注释规则,对程序源码进行文档化。换句话说,就是在对程序源码添加注释时,要按照 Doxygen 的游戏规则来搞。
Doxygen 的注释类型可分为:
行间注释:注释语句不与程序源码出现在同一行,主要用于注释头文件中出现的结构体 (struct)、枚举 (enum)、联合 (uion) 等数据类型,以及程序接口的功能与使用约定;
行内注释:注释语句与程序源码出现在同一行内,主要用于代码的局部注释。
Doxygen 认可的行间注释标记见下例:
/*!
* 这是行间注释标记示例
*/
Doxygen 认可的行内注释标记见下例:
typedef struct {
double coord[3]; /*!< 这是行内注释示例 */
}M2_3D_Point;
请仔细观察以上注释示例中所使用的注释标记。Doxygen 也允许使用其它类型的注释标记,但是我们通常没必要知道茴香豆的“茴”字有几种写法,只需要知道一种就可以了。
下面回顾一下 C 程序源码中的注释类型:
文件的注释:用于解释当前文件的用途、作者、创建及修改日期等信息;
数据类型的注释:用于解释数据类型的意义;
程序接口的注释:用于解释程序接口的功能、使用约定等信息;
还有,就是还有,我还没想出来……也许以后用着用着 doxygen,就想起来了,到时候再来这里添上新东西。
我总觉得自己在不停的说着废话,最直接了当的做法就是停下唠叨,参照doxygen 手册中的 commands.html 页面,阅读下面的示例文档,它们都是 .h 文件。当然,在 .c 文件中也允许出现注释,但我认为它们不应该出现在程序文档中,使用 C 语言最重要的一个原则就是:.h 文件是用来声明的,类似于文章的目录或索引;而 .c 文件是用来实现的,类似文章的正文。
Step 3: 程序文档生成
现在开始生成程序文档,将终端的工作目录定位在 m2-list 目录,然后键入:
$ doxygen your-cfg-filename
your-cfg-filename 是 Step 1 中生成的 Doxygen 配置文件名,如果是使用 "doxygen -g" 生成的配置文件——Doxyfile,那么可以在终端里仅键入 "doxygen" 命令即可生成程序文档。
生成的文档位于 m2-list/doc/html 目录中,使用浏览器打开该目录中的 index.html 文件,即可看到自己的工作成果。
小结
本文仅仅是个很小很小的开始,许多我很想说的东西,由于拙于 & 懒于表达,都没有讲出来。如果这篇文章能够引起你对 Doxygen 的兴趣,并尝试在工作中使用它,我就心满意足了。实际上,Doxygen 给我的帮助不仅仅是生成程序文档,更重要的是它提示我应该怎样对程序进行良好的注释!
最后,要感谢 Doxygen 的开发者,说中文也许你们听不懂,那我 say 一句 “tks a lot”.
doxygen 命令_使用 Doxygen 制作 C 程序文档相关推荐
- doxygen 命令_学习用 doxygen 生成源码文档
学习用 doxygen 生成源码文档 Arpan Sen 2008 年 10 月 13 日发布 维护用 C/C++ 开发的遗留系统并添加新特性是一项艰难的任务.这涉及几方面的问题:理解现有的类层次结构 ...
- doxygen 命令_doxygen使用
前言 下面主要讲解linux下Doxygen命令行实现html文档生成的操作,当然也有界面版本操作方式,linux下安装doxygen-gui即可通过doxywizard开启界面操作,windows下 ...
- doxygen 命令_Doxygen
Doxygen Linux 1. 安装 安装Doxygen$ sudo apt-get install doxygen 安装Graphviz$ sudo apt-get install graphvi ...
- doxygen 命令_doxygen使用总结
doxygen [功能] 为许多种语言编写的程序生成文档的工具. [举例] *生成一个模板配置文件,模板文件中有详细的注释: $doxgen -g test 这样,会生成一个test文件,1500多行 ...
- 昊鼎王五:Windows运行中的所有命令_Windows快捷命令_运行中的所有命令
昊鼎王五:Windows运行中的所有命令_Windows快捷命令_"运行"中的所有命令 winver 检查Windows版本 wmimgmt.msc 打开Windows管理体系结构 ...
- 计算机基础应用软件ppt制作,大学计算机基础_演示文稿制作软件.ppt
大学计算机基础_演示文稿制作软件资料 插入影片和声音 插入影片 插入声音 播放CD乐曲 录制声音 5.5 演示文稿中的动画和超链接技术 5.5.1 为幻灯片加入动画效果 5.5.2 创建超级链接 为幻 ...
- 不用公钥批量部署机器执行命令_模版
批量部署机器执行命令_小模版 案例: 脚本目的:两台以上机器(ip:172.16.1.187和172.16.1.188)去拷贝主控制机器IP:172.16.1.199上目录/liang/下的ceshi ...
- 一条命令(dd)制作Centos(Linux)优盘(U盘)启动盘
简介 这篇文章主要介绍了一条命令(dd)制作Centos(Linux)优盘(U盘)启动盘以及相关的经验技巧,文章约1098字,浏览量484,点赞数9,值得推荐! 整个过程已录制成视频并上传腾讯课堂. ...
- js拆字_分图程序 _制作个人字体_手写字制作ttf字体方法
js拆字_分图程序 _制作个人字体_手写字制作ttf字体方法 前言 FontForgeBuilds制作ttf FontForgeBuilds制作个人字体 Adobe_Fireworks_CS5批量转换 ...
最新文章
- php进程学习(一)
- android 检测应用程序信息
- Asp.Net MVC 教程
- python装饰器函数传参
- php mysql 平均分_平均评级计算mysql php
- asp.net将内容导出到Excel,Table表格数据(html)导出EXCEL
- 花旗银行文章解释DeFi的好处
- mysql sysdate 格式化_MySQL函数汇总
- Python爬虫 抓取拉勾招聘信息
- 基于MPLS的VPLS
- state_dict详解--存放训练过程中需要学习的权重和偏执系数
- 从王自如和老罗的论战中我貌似懂得了点神马...
- 微信根据Media_id下载录音报错readfile(): Peer certificate CN=`mp.weixin.qq.com‘ did not match expected CN=`file
- Flink 系例 之 CountWindowAll
- 闲谈swi与ucos-续篇
- iterm快捷键及操作技巧(附Linux快捷键)
- manifest.json 解析--手机web app开发笔记(三-2)
- 黄金原野 可信身份链:数字身份+区块链
- 使用python使用正则表达式进行查找和替换re.sub方法
- ​华硕好屏突破120Hz超高刷新率,笔电界新晋卷王——华硕无双叫人心动
热门文章
- distribute-list
- 电脑通过诺基亚E71上网
- 外籍在读博士|赴新西兰奥克兰大学双院士导师麾下联合培养
- 计算机的声音怎么设置在哪设置方法,电脑声音怎么设置 电脑声音设置方法步骤...
- 金仓数据库KingbaseES监控工具—kmonitor问题及解决方法
- 很老的文章:Mapbar:地图搜索的人民战争
- 万用表怎么测量电池容量_电工知识:用万用表怎么测量电车电池的好坏?简单分析5种耗电...
- java获取鼠标在屏幕中的位置 方法一_Java如何获取鼠标指针的位置?
- Android 工程编译过程
- 【Python】将微信收藏的文章批量导出为pdf