doxygen教程-4-快速上手配置文件
文章目录
- 快速上手 doxygen 配置文件
- 配置文件的格式
- 常用 tag 简介
- OUTPUT_DIRECTORY
- INPUT 和 RECURSIVE
- EXTRACT_ALL
- OUTPUT_LANGUAGE
- GENERATE_LATEX
前面提到使用 doxygen 实际上就是做好两件事: 写配置和写注释, 本文将初步介绍 doxygen 的配置文件.
快速上手 doxygen 配置文件
doxygen 的配置文件是一个纯文本文件. 虽然用 Windows 自带的记事本就可以编辑, 但是为了更好的体验, 以下使用 Notepad++ 编辑配置文件.
我们已经知道, 命令 doxygen -g
生成模板配置文件, 参数中没有指定文件名, 所以使用了默认的文件名 Doxyfile
. 右键, 选择用 Notepad++ 打开这个模板配置文件.
打开之后会看到许多类似下面这样的英文:
其中以 #
开头的一行是配置文件的注释, 会被 doxygen 忽略, 而类似 TAG_NAME = xxx
的语句, 则是我们要关心的设置. 等号的左侧是个 tag, 即标签, 而等号的右侧, 是该 tag 的值(value). 这里的注释告诉我们, 这个 name 会被用在大多数页面的标题中, 默认值是 "My Project"
. 我们试着修改这个默认值
PROJECT_NAME = "Hello Project"
然后run doxygen Doxyfile
重新生成文档, 看看网页发生了什么变化
我们发现, 网页左上角的标题变成了我们刚刚修改的文本.
接下来找到另外两个 tag 并修改为以下值.
PROJECT_NUMBER = v1.0
PROJECT_BRIEF = "say hello to doxygen"
重新生成文档, 刷新网页.
可以看到, 在标题的周围, 多了版本号和简介.
可以推测, 其他的 tag 也是一样的套路. 我们通过这种方式, 告诉 doxygen 我们想要输出怎样的文档.
配置文件的格式
在继续之前, 我们先看看官方手册对配置文件的准确规定吧. 以下内容摘自 Reference Manual - Configuration 一节.
A configuration file is a free-form ASCII text file with a structure that is similar to that of a Makefile, with the default name Doxyfile. It is parsed by doxygen. The file may contain tabs and newlines for formatting purposes. The statements in the file are case-sensitive. Comments may be placed anywhere within the file (except within quotes).
…
Comments begin with the hash character (#) and ends at the end of the line.
The file essentially consists of a list of assignment statements. Each statement consists of a TAG_NAME written in capitals, followed by the equal sign (=) and one or more values. If the same tag is assigned more than once, the last assignment overwrites any earlier assignment. For tags that take a list as their argument, the += operator can be used instead of = to append new values to the list. Values are sequences of non-blanks. If the value should contain one or more blanks it must be surrounded by quotes ("…"). Multiple lines can be concatenated by inserting a backslash () as the last character of a line. Environment variables can be expanded using the pattern $(ENV_VARIABLE_NAME).
什么是 “free-form ASCII text file” 我也不理解, 不过从其余的叙述中, 我们可以得到以下信息:
- 配置文件内的语句对大小写敏感.
- 注释以
#
开头, 在行末结束. - 配置文件的内容主要是一系列的赋值语句.
- 对同一个 tag 多次赋值, 最后一次赋值会覆盖前面的.
- 如果 tag 接受一个列表作为参数, 则使用
+=
而不是=
来添加新值. - 如果一条语句要跨多行, 则要在一行要以
\
结尾. - 可以使用环境变量.
常用 tag 简介
官方手册里可以找到所有 tag 的介绍, 而且还提供了索引以便查找. 下面介绍一些常用的 tag, 权当抛砖引玉, 以加深初学者对于配置文件功能的认知.
OUTPUT_DIRECTORY
顾名思义, 该 tag 指定文档的输出目录. 如果是相对路径, 则相对于 doxygen 启动的目录(即工作目录). 如果留空, 则使用对当前目录.
在前面的教程中, 我们创建了一个项目 hello_doxygen
, 生成文档后的目录结构是这样的:
|--hello_doxygen\|--html\|--latex\|--Doxyfile|--hello.c
可以看到, 其中 html\
和 latex\
是生成的文档, 但是直接输出到了项目目录下. 对于有洁癖的程序猿来说, 通常会期望把文档的输出放到一个专门的文件夹中, 例如 doxygen_output
.
先给 tag 赋值 OUTPUT_DIRECTORY = doxygen_output
, 然后 run doxygen, 输出文档后的目录结构应该变成了这样:
|--hello_doxygen\|--doxygen_output\|--html\|--latex\|--Doxyfile|--hello.c
这里有个小细节, 相对路径是相对于工作目录的, 上面是工作目录为 hello_doxygen
时的结果. 也就是, 终端里的显示是这样的:
C:\hello_doxygen>doxygen Doxyfile
提个小问题. 如果在 hello_doxygen
的父目录运行命令, 输出文档会发生什么呢? 就留给读者取探索了. 此时终端的显示应该是这个样子(注意提示符>
以及命令的参数):
C:\>doxygen hello_doxygen/Doxyfile
INPUT 和 RECURSIVE
INPUT
指出用作输入的源文件是什么, 它的值可以是文件, 也可以是目录, 每个值用空格隔开. 源文件可以是代码, 如 .c
, .h
, 也可以是其他 doxygen 支持的文件, 如 .md
, .dox
. 下面是一个例子:
INPUT = user \lib \main.c
如果该 tag 留空的话, 则默认它的值是当前目录(工作目录).
RECURSIVE
则指出是否要递归地在 INPUT
给出的目录的子目录中搜索源文件. 它的值为 YES 或 NO.
EXTRACT_ALL
默认情况下, EXTRACT_ALL = NO
, doxygen 输出的文档中, 只包含那些已按 doxygen 语法注释的 entity (documented entities). 而如果设为 YES, 则 doxygen 会将所有的 entity 写入文档, 当然, static 和 private 的 entity 除外.
还是以前面的项目 hello_doxygen
为例. 我们把 hello.c
改成如下内容:
/**@file hello.c *//*** @brief A hello func.* @details This hello function does nothing.*/
void hello(){// do nothing
}void undocumented_hello() {}
我们先以 EXTRACT_ALL = YES
跑一次 doxygen. 然后点击 Files-hello.c, 网页是这个样子的:
可以看到 “Function Documentation” 下有函数 undocumented_hello()
, 但是里面没有任何内容. 这是当然的啦, 因为我们没有为它写任何注释.
然后将配置改成 EXTRACT_ALL = NO
, 输出文档, 刷新网页, 结果变成了这样:
“Functinos” 下 undocumented_hello()
不再是超链接的样式, “Function Documentation” 也没了这个函数.
除此之外, doxygen 还有一条规则, 原文是这样的:
To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).
总的来说就是, 要让 doxygen 把低层次的注释放到输出的文档中, 必须先做高层次的注释. 这个在后面还会举例解释, 这里先了解, 对于所有 entity 来说, 文件的层次最高了, 因此必须注释文件, 也就是源文件中至少必须有这一句 /**@file*/
, 否则输出的文档中是没有这个文件中的内容的.
这是一个常常被忽视的问题, 如果发现明明给函数写的注释完全符合规则, 但是输出的文档却看不到, 可能就是没有注释源文件. 感兴趣的读者可以试着把 hello.c
的第一句注释 /**@file hello.c */
删除掉再运行 doxygen, 看看输出的文档包含哪些内容.
之所以提这个问题, 是因为 EXTRACT_ALL = YES
时, 会把所有 entity 都记录在文档上, 那么文件是否被注释就没有那么重要了.
光看文字描述容易绕进去, 若按下表输出hello_doxygen
的文档, 把各种搭配都试一遍, 也许就清楚了.
有无 /**@file*/
|
EXTRACT_ALL
|
输出的文档有无hello.c内容 |
---|---|---|
有 | NO | 有 |
无 | NO | 无 |
无 | YES | 有 |
OUTPUT_LANGUAGE
该 tag 用于指定文档框架的语言. 文档的内容本身是来自于注释的, 所以注释写了什么, 文档内容就是什么, 不存在自动翻译的. 这里的语言是指文档框架, 即网页上那些固定的文字所使用的语言. 前面的例子, 使用的都是默认值 OUTPUT_LANGUAGE = English
, 而如果我们改为 OUTPUT_LANGUAGE = Chinese
, 那么页面就会变成下面这样子:
除了中文之外, doxygen 还支持许多其他的语言, 详情请看配置模板中, 该 tag 前的注释.
GENERATE_LATEX
最开始提到, 本套教程只涉及 html 输出, 大多数场合下也只需要 html 输出. 但是默认情况下, doxygen 同时还生成了 latex 输出. 对于有洁癖的人来说, 产生了多余的东西会很难受, 所以就要设置 GENERATE_LATEX = NO
.
设置为 NO 以后, 删掉之前输出的文档, 重新生成一遍, 这次是不是就只有 html 输出了?
doxygen教程-4-快速上手配置文件相关推荐
- 使用CycleGAN训练自己制作的数据集,通俗教程,快速上手
总结了使用CycleGAN训练自己制作的数据集,这里的教程例子主要就是官网给出的斑马变马,马变斑马,两个不同域之间的相互转换.教程中提供了官网给的源码包和我自己调试优化好的源码包,大家根据自己的情况下 ...
- GNU Radio 教程(1)-快速上手
目录 GNU Radio是什么 在Windows上安装GNU Radio 界面介绍 快速上手 申明: 文章内容参考了wiki.gnuradio.org, 和White-Alone的Radio系列教程. ...
- React 教程:快速上手指南
翻译:疯狂的技术宅 原文:https://www.toptal.com/react/... 本文首发微信公众号:jingchengyideng 欢迎关注,每天都给你推送新鲜的前端技术文章 前端和 Ja ...
- 如何把照片做成视频?抖音爆款的图片视频切换教程,快速上手!
现在都流行用照片随手记录生活.而把照片做成视频,又是现在刷爆抖音.朋友圈的形式.不仅有酷炫的图片切换效果,还带有动听的背景音乐,这样精美又吸睛的照片视频,肯定能让你获得超多赞.今天就教大家用数码大师快 ...
- 涂鸦 Wi-Fi SDK开发系列教程——3. 快速上手
本系列课程面向有嵌入式开发经验的同学,用来介绍如何在涂鸦的Wi-Fi系列模组和Wi-Fi&Bluetooth LE系列模组上进行二次开发. 上篇回顾:Wi-Fi模组二次开发--SoC开发环境搭 ...
- Visual Studio 2019/2017 安装使用教程(快速上手版)
Visual Studio 2017 安装使用教程(详细) 在此鸣谢范华对本文工作的大力支持 一.下载 二.安装 2017版本新建项目过程 2019版本新建项目过程 新建源文件 然后你就可以简单编写一 ...
- kafka使用教程、快速上手
kafka概述 一.kafka概述 1.1 定义 1.2 消息队列 1.2.1 传统消息队列的应用场景 1.2.2 消息队列的两种形式 1.3 Kafka 基础架构 二.kafka安装部署 2.1安装 ...
- Redux入门教程(快速上手)
典型的Web应用程序通常由共享数据的多个UI组件组成.通常,多个组件的任务是负责展示同一对象的不同属性.这个对象表示可随时更改的状态.在多个组件之间保持状态的一致性会是一场噩梦,特别是如果有多个通道用 ...
- ToolBar使用教程(小白快速上手)
ToolBar效果展示:(做工粗糙,有那个意思就行了) 概述: 在toolbar出来之前,对于标题栏的操作,小伙伴接触比较多的应该是ActionBar了.这里说明下啊,使用ToolBar能都实现和Ac ...
最新文章
- cocos 时间函数需要什么引用_2021国家公务员考试时间是什么时候 国考备考时间需要多久...
- opencv matlab测距,基于MATLAB和OpenCV的双目视觉测距系统的实现
- lucene、solr、nutch三者的关系
- tcp连接的三次握手
- c0000005错误怎么解决_iTunes提示3194未知错误怎么办【解决方法】
- MYSQL--事务处理
- css不支持data image,CSS_CSS中使用image data URI来处理图片的方法,即将图片资源转换为 base64 字 - phpStudy...
- yum安装Docker失败No package docker available
- go编译库给c语言函数返回值,go语言 函数return值的几种情况
- Windows编程之互动与动画
- 1235813找规律第100个数_人教版一年级下册数学第1-8单元知识点梳理填空,附答案...
- 是什么让你踏上了程序员的道路?
- Python爬虫的requests模块你真的学会了吗?来看看这些高级用法!
- 【开源毕设】一款精美的家校互动APP分享——爱吖校推 [你关注的,我们才推](持续开源更新2)...
- 字符————ASC II码
- Distral: Robust multitask reinforcement learning.
- php数字验证码代码,php中文字母数字验证码实现代码
- KTV评分系统实现总结
- 敏捷项目管理 第2版[JimHighsmith](一)
- 很好的东子(干货很多)--把一个函数变成全局的方法及slideToggle()
热门文章
- Hadoop学习笔记 --- YARN执行流程与工作原理
- 判断 1000-2000 年之间的闰年
- java实现RSA和AES加密(一)
- 易飞:订单单头税率与单身税率不符导致销货单无法开窗选择
- oracle 导入ar税率,EBS(Oracle ERP) AR AP TAX 税信息 区别 转
- C语言检测电池,教你如何用万用表判断充电电池的好坏 - 全文
- 计算机一级可以积分入深户吗,计算机软考中级能入深户吗?怎样报名考取
- pta——大笨钟的心情,稳赢,统计一行文本的单词个数(c语言)
- python做简单的游戏名字_python猜名字游戏
- 数据分析与可视化内容整理