资源

正文

安装

快速开始

从一个项目中使用如下命令初始化 Doxygen 配置文件：

shell

doxygen -g

得到 Doxyfile 文件。编辑其中的文本即可修改项目配置。

提示

几个关键配置项：

配置项	说明	示例
`PROJECT_NAME`	项目名称	`PROJECT_NAME = "MyProject"`
`OUTPUT_DIRECTORY`	文档输出目录	`OUTPUT_DIRECTORY = docs`
`INPUT`	源码目录或文件	`INPUT = src include`
`RECURSIVE`	是否递归搜索 `INPUT` 目录	`RECURSIVE = YES`
`EXTRACT_ALL`	是否提取未注释函数	`EXTRACT_ALL = YES`
`GENERATE_HTML`	是否生成 HTML 文档	`GENERATE_HTML = YES`
`GENERATE_LATEX`	是否生成 LaTeX / PDF 文档	`GENERATE_LATEX = NO`（如果暂时不需要）
`HAVE_DOT`	是否使用 Graphviz 绘制类图	`HAVE_DOT = YES`（需安装 Graphviz）
`CALL_GRAPH`	是否生成函数调用图	`CALL_GRAPH = YES`
`CALLER_GRAPH`	是否生成调用者图	`CALLER_GRAPH = YES`

这里根据工程情况（江科大 STM32 的 OLED 范例工程：STM32入门教程）作出修改：

INPUT = Hardware System
RECURSIVE = YES
GENERATE_LATEX = NO
EXTRACT_ALL = YES

注意

Doxygen 支持如下格式的文件：

Extension	Language	Extension	Language	Extension	Language
.dox	C / C++	.HH	C / C++	.py	Python
.doc	C / C++	.hxx	C / C++	.pyw	Python
.c	C / C++	.hpp	C / C++	.f	Fortran
.cc	C / C++	.h++	C / C++	.for	Fortran
.cxx	C / C++	.mm	C / C++	.f90	Fortran
.cpp	C / C++	.txt	C / C++	.f95	Fortran
.c++	C / C++	.idl	IDL	.f03	Fortran
.cppm	C / C++	.ddl	IDL	.f08	Fortran
.ccm	C / C++	.odl	IDL	.f18	Fortran
.cxxm	C / C++	.java	Java	.vhd	VHDL
.c++m	C / C++	.cs	C#	.vhdl	VHDL
.ii	C / C++	.d	D	.ucf	VHDL
.ixx	C / C++	.php	PHP	.qsf	VHDL
.ipp	C / C++	.php4	PHP	.l	Lex
.i++	C / C++	.php5	PHP	.md	Markdown
.inl	C / C++	.inc	PHP	.markdown	Markdown
.h	C / C++	.phtml	PHP	.ice	Slice
.H	C / C++	.m	Objective-C
.hh	C / C++	.M	Objective-C

如果工程中的函数被正确地注释：

#include "stm32f10x.h"
 
/**
  * @brief  微秒级延时
  * @param  xus 延时时长，范围：0~233015
  * @retval 无
  */
void Delay_us(uint32_t xus)
{
	SysTick->LOAD = 72 * xus;				//设置定时器重装值
	SysTick->VAL = 0x00;					//清空当前计数值
	SysTick->CTRL = 0x00000005;				//设置时钟源为HCLK，启动定时器
	while(!(SysTick->CTRL & 0x00010000));	//等待计数到0
	SysTick->CTRL = 0x00000004;				//关闭定时器
}
 
/**
  * @brief  毫秒级延时
  * @param  xms 延时时长，范围：0~4294967295
  * @retval 无
  */
void Delay_ms(uint32_t xms)
{
	while(xms--)
	{
		Delay_us(1000);
	}
}
 
/**
  * @brief  秒级延时
  * @param  xs 延时时长，范围：0~4294967295
  * @retval 无
  */
void Delay_s(uint32_t xs)
{
	while(xs--)
	{
		Delay_ms(1000);
	}
}

则可以通过下列命令生成文档：

shell

doxygen Doxyfile

Doxygen version used: 1.14.0 (XXX)
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
Searching for plantuml files...
Searching for files to exclude
Searching INPUT for files to process...
Searching for files in directory D:/Users/Documents/Study/Temp/Hardware
Searching for files in directory D:/Users/Documents/Study/Temp/System
Reading and parsing tag files
Parsing files
Preprocessing D:/Users/Documents/Study/Temp/Hardware/Key.c...
Parsing file D:/Users/Documents/Study/Temp/Hardware/Key.c...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/Key.h...
Parsing file D:/Users/Documents/Study/Temp/Hardware/Key.h...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/LED.c...
Parsing file D:/Users/Documents/Study/Temp/Hardware/LED.c...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/LED.h...
Parsing file D:/Users/Documents/Study/Temp/Hardware/LED.h...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/OLED.c...
Parsing file D:/Users/Documents/Study/Temp/Hardware/OLED.c...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/OLED.h...
Parsing file D:/Users/Documents/Study/Temp/Hardware/OLED.h...
Preprocessing D:/Users/Documents/Study/Temp/Hardware/OLED_Font.h...
Parsing file D:/Users/Documents/Study/Temp/Hardware/OLED_Font.h...
Preprocessing D:/Users/Documents/Study/Temp/System/Delay.c...
Parsing file D:/Users/Documents/Study/Temp/System/Delay.c...
Preprocessing D:/Users/Documents/Study/Temp/System/Delay.h...
Parsing file D:/Users/Documents/Study/Temp/System/Delay.h...
Building macro definition list...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Building class list...
Building concept list...
Computing nesting relations for classes...
Associating documentation with classes...
Associating documentation with concepts...
Associating documentation with modules...
Building example list...
Searching for enumerations...
Searching for documented typedefs...
Searching for members imported via using declarations...
Searching for included using directives...
Searching for documented variables...
Building interface member list...
Building member list...
Searching for friends...
Searching for documented defines...
Computing class inheritance relations...
Computing class usage relations...
Flushing cached template relations that have become invalid...
Warn for undocumented namespaces...
Computing class relations...
Add enum values to enums...
Searching for member function documentation...
Creating members for template instances...
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Computing module relations...
Sorting lists...
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding xrefitems...
Sorting member lists...
Setting anonymous enum type...
Computing dependencies between directories...
Generating citations page...
Counting members...
Counting data structures...
Resolving user defined references...
Finding anchors and sections in the documentation...
Transferring function references...
Combining using relations...
Adding members to index pages...
Correcting members for VHDL...
Computing tooltip texts...
Generating style sheet...
Generating search indices...
Generating example documentation...
Generating file sources...
Generating code for file Hardware/Key.h...
Generating code for file Hardware/LED.h...
Generating code for file Hardware/OLED.h...
Generating code for file Hardware/OLED_Font.h...
Generating code for file System/Delay.h...
Generating file documentation...
Generating docs for file Hardware/Key.c...
Generating docs for file Hardware/Key.h...
Generating docs for file Hardware/LED.c...
Generating docs for file Hardware/LED.h...
Generating docs for file Hardware/OLED.c...
D:/Users/Documents/Study/Temp/Hardware/OLED.c:111: warning: argument '鏃? of command @param is not found in the argument list of OLED_Clear(void)
D:/Users/Documents/Study/Temp/Hardware/OLED.c:111: warning: found documented return type for OLED_Clear that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:52: warning: found documented return type for OLED_I2C_SendByte that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:27: warning: argument '鏃? of command @param is not found in the argument list of OLED_I2C_Start(void)
D:/Users/Documents/Study/Temp/Hardware/OLED.c:27: warning: found documented return type for OLED_I2C_Start that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:40: warning: argument '鏃? of command @param is not found in the argument list of OLED_I2C_Stop(void)
D:/Users/Documents/Study/Temp/Hardware/OLED.c:40: warning: found documented return type for OLED_I2C_Stop that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:268: warning: argument '鏃? of command @param is not found in the argument list of OLED_Init(void)
D:/Users/Documents/Study/Temp/Hardware/OLED.c:268: warning: found documented return type for OLED_Init that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:98: warning: found documented return type for OLED_SetCursor that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:251: warning: found documented return type for OLED_ShowBinNum that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:129: warning: found documented return type for OLED_ShowChar that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:226: warning: found documented return type for OLED_ShowHexNum that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:181: warning: found documented return type for OLED_ShowNum that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:198: warning: found documented return type for OLED_ShowSignedNum that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:151: warning: found documented return type for OLED_ShowString that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:70: warning: found documented return type for OLED_WriteCommand that does not return anything
D:/Users/Documents/Study/Temp/Hardware/OLED.c:84: warning: found documented return type for OLED_WriteData that does not return anything
Generating docs for file Hardware/OLED.h...
Generating docs for file Hardware/OLED_Font.h...
Generating docs for file System/Delay.c...
D:/Users/Documents/Study/Temp/System/Delay.c:19: warning: found documented return type for Delay_ms that does not return anything
D:/Users/Documents/Study/Temp/System/Delay.c:32: warning: found documented return type for Delay_s that does not return anything
D:/Users/Documents/Study/Temp/System/Delay.c:5: warning: found documented return type for Delay_us that does not return anything
Generating docs for file System/Delay.h...
Generating page documentation...
Generating group documentation...
Generating class documentation...
Generating concept documentation...
Generating module documentation...
Generating namespace documentation...
Generating graph info page...
Generating directory documentation...
Generating dependency graph for directory Hardware
Generating index page...
Generating page index...
Generating topic index...
Generating module index...
Generating module member index...
Generating namespace index...
Generating namespace member index...
Generating concept index...
Generating annotated compound index...
Generating alphabetical compound index...
Generating hierarchical class index...
Generating graphical class hierarchy...
Generating member index...
Generating file index...
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
Running dot...
Generating dot graphs using 9 parallel threads...
Running dot for graph 1/8
Running dot for graph 2/8
Running dot for graph 3/8
Running dot for graph 4/8
Running dot for graph 5/8
Running dot for graph 6/8
Running dot for graph 7/8
Running dot for graph 8/8
Patching output file 1/7
Patching output file 2/7
Patching output file 3/7
Patching output file 4/7
Patching output file 5/7
Patching output file 6/7
Patching output file 7/7
type lookup cache used 31/65536 hits=20 misses=31
symbol lookup cache used 52/65536 hits=32 misses=52
finished...

得到如下：

## 转为 Markdown

Doxygen 不支持生成 Markdown 文件，但是可以通过生成 XML 文件后再使用 doxybook2 曲线救国！下载 doxybook2 并设置环境变量。

在 Doxyfile 中设置：

GENERATE_XML = YES
XML_OUTPUT = xml

设置输入/输出路径（输出的文件夹必须存在）以将生成的 xml 转为 markdown：

doxybook2 -i D:/Users/Documents/Study/Temp/xml -o D:/Users/Documents/Study/Temp/md_docs