Doxygen 是一种用于 C/C++、Java™、Python 和其他编程语言的文档系统, 其功能类似于 java.
1. 安装doxygen
sudo apt-get graphviz
./configure --prefix=/home/user1/bin
2. 使用doxygen生成文档
3. 编辑配置文件 Doxyfile
- <OUTPUT_DIRECTORY>:必须在这里提供一个目录名,例如 /home/user1/documentation,这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名,doxygen 会以这个名称创建具有适当用户权限的目录。
- <INPUT>:这个标记创建一个以空格分隔的所有目录的列表,这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如,请考虑以下代码片段:
INPUT = /home/user1/project/kernel /home/user1/project/memory
在这里,doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录,其中有多个子目录,那么只需指定根目录并把<RECURSIVE> 标记设置为
Yes。- <EXCLUDE>:
从文档目录排除相应的目录
- <FILE_PATTERNS>:在默认情况下,doxygen 会搜索具有典型 C/C++ 扩展名的文件,比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 标记没有相关联的值,doxygen 就会这样做。如果源代码文件采用不同的命名约定,就应该相应地更新这个标记。例如,如果项目使用 .c86 作为 C 文件扩展名,就应该在
<FILE_PATTERNS> 标记中添加这个扩展名。
- <RECURSIVE>:如果源代码层次结构是嵌套的,而且需要为所有层次上的 C/C++ 文件生成文档,就把这个标记设置为 Yes。例如,请考虑源代码根目录层次结构 /home/user1/project/kernel,其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为
Yes,doxygen 就会递归地搜索整个层次结构并提取信息。
- <EXTRACT_ALL>:这个标记告诉 doxygen,即使各个类或函数没有文档,也要提取信息。必须把这个标记设置为Yes。
- <EXTRACT_PRIVATE>:把这个标记设置为Yes。否则,文档不包含类的私有数据成员。
- <EXTRACT_STATIC>:把这个标记设置为Yes。否则,文档不包含文件的静态成员(函数和变量)。
4. doxygen 中的特殊标记
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER
只展开宏 CONTAINER .
5. 生成图形和图表
<CLASS_DIAGRAMS>:在 Doxyfile 中这个标记默认设置为 Yes。如果这个标记设置为 No,就不生成继承层次结构图。
<HAVE_DOT>:如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes,<CLASS_DIAGRAMS> 标记就无效了。
<CLASS_GRAPH>:如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes,就使用 dot 生成继承层次结构图,而且其外观比只使用 <CLASS_DIAGRAMS> 时更丰富。
<COLLABORATION_GRAPH>:如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes,doxygen 会生成协作图(还有继承图),显示各个类成员(即包含)及其继承层次结构。
6. 代码文档样式
/**
* text...
*
*/
也可以加一些标记, '@' 和 '/' 等价:
/**
* @brief bababa
*
* detailed info....
*
*/
----------------------------- Example Begin ---------------------------------
///@file socket_c.h head file of class socket_c.
///Define the interface of class socket_c.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $ 这是普通注释, 不会生成在文档中
///@brief class of server socket.
class socket_c
{
private:
public:
///@brief handle the connections of clients.
///@param server the server ip address.
///@param serv_port the server #port.
///@return connected socketfd.
# 具体返回值的注释,格式: ///@retval 返回值 该返回值的注释.
///@retval connfd on success.
///@retval 0 on EINTR - system call.
///@retval -1 on error.
# 参见...,格式: ///@see 参见的类/文件等.
///@see main_ppc.cpp
int accept_client(const int listenfd);
};
///@brief structure of child process.
struct child_proc_s
{
# 行尾的注释,格式: ///< 注释内容.
pid_t child_pid; ///<child process id.
int child_pipefd; ///<parent's stream pipe to/from child.
};
# 全局变量的注释,也可以采用上面的行尾格式进行注释.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------
7. 在vim中使用Doxygen插件: DoxygenToolkit
let g:doxygenToolkit_authorName="your name"
let g:doxygenToolkit_briefTag_funcName="yes"