doxygen

Table of Contents

intro

支持的语言

doxygen 是支持很多种编程语言的文档系统,它到目前支持:

  1. c++
  2. c
  3. java
  4. objective-c
  5. python
  6. idl
  7. fortran
  8. vhdl
  9. php
  10. c#

它可以做以下一些事情:

用途

  1. 从代码源文件中(依据代码结构和特定结构的注释)生成文档,可以非常容易保持文档和源代码的同步,它支持生成文档的格式有:
    • html(最流行和广泛使用的,易于在线发布)
    • Latex
    • rtf(ms word)
    • Postscript
    • PDF
    • man
  2. 在需要了解没有文档的大项目的时候, 可以配置doxygen来生成代码结构图, 以可视化的方式来表现include依赖关系、继承关系、友元关系等等来辅助快速了解项目梗概。
  3. 甚至可以脱离代码,仅仅用doxygen来创建一般文档。

优势

  1. 跨平台(可在mac,linux,win,unix,bsd上运行)
  2. 使用广泛,是在大部分c/c++文档系统的选择(特别是开源项目),所以成了事实上的标准
  3. 输出样式可自定义,比如你生成的是html文档,则其文档格式较为规整,可调整css文件直接调整文档样式

下载和安装

使用

  1. 从代码生产文档或者结构图

    win下面图示生成文档和关系图的说明

    具体如何控制生成uml,或者其他类型的结构图以及文档样式控制等,下面章节的资料链接有详细说明。

  2. 快捷的在代码中写入doxygen风格的注释(以emacs为例,vc,source insight网上也有相关说明)

    其实是要简单看一下doxygen注释风格,以后写注释依照这样的标准来写就可以使用doxygen自动生产文档了, 不过还是可以依靠一些辅助工具来辅助我们更方便的生产这种标准注释,下面结合不同的开发环境介绍一些辅助工具。

emacs doxygen

emacs + doxygen = doxymacs

为了方便在emacs中方便的使用doxygen,主要包括查询doxygen风格的注释,和编辑代码时插入doxygen风格的注释,高亮doxygen关键,字当然还有生产文档等。

doxymacs项目主页

doxymacs 需求

使用doxymacs 需要一些一些东西:

  1. w3(现在emacs一般自带,印象中是emacs中的浏览器)
  2. tempo(emacs自带,不知从何版本开始,起码23.3自带)
  3. libxml2

doxymacs下载

doxymacs 安装

如果你是linux等环境, 有方便的gnu编译环境,则执行以下命令,(猜测编译过程一个是编译成elc加速,一个是自动安装到标准位置) 如果不方便,或者不想编译也可以跳过,直接将下载好的压缩包解压放在某目录下。

$ ./configure
$ make
$ make install

doxymacs 配置

将相关路径加进来,如果你执行了上面的编译安装,则默认会放在/usr/share/emacs/site-lisp/ win不知道在什么地方,如果没有执行 上面的编译安装过程,则需要将下载的doxymacs解压目录下的lisp目录,类似这样/**/**/doxymacs/lisp/加入到emacs路径中,即在.emacs中加入:

(add-to-list 'load-path "~/.emacs.d/doxymacs-1.8.0/lisp")
(require 'doxymacs)
;; 下面一句自动在c c++ mode下面打开doxymacs minor mode
(add-hook 'c-mode-common-hook 'doxymacs-mode)

好,到这里doxymacs就配置好了

doxymacs 使用

默认的使用大概记住以下几个快捷键就可以了:

C-c d ? 查看光标所在的当前符号的文档
C-c d r 重新扫描doxygen tags 文件
C-c d f 插入下个函数的doxygen注释
C-c d i 插入当前文件的doxygen注释
C-c d ; 为当前行的成员变量插入注释,类似M-;
C-c d m 插入空的多行doxygen注释
C-c d s 插入空的单行注释
C-c d @ 为当前区域插入群注释

例如,在emacs中打开一个temp.cpp文件,按下 C-c d i,则自动插入以下内容, 并将光标停留在合适位置等待写入

/**
 * @file   temp.cpp
 * @author user   <user@gmail.com>
 * @date   Sat Apr  9 00:10:33 2011
 *
 * @brief
 *
 *
 */

然后就可以将doxygen工具与开发的工程配置在一起,比如每次make的时候除了编译代码,也自动使用doxygen生成文档,保持同步。

source insight doxygen

资料链接