Linux 下使用Doxygen

Doxygen 是支持多种语言的文档生成工具。也许在编码前能把设计文档写好,再来编写代码是正确的一件事情,当由于中间编码过程中任务的修改或者代码的优化等原因,会导致开始所写的文档变动非常大,于是在编码前写好文档对于大多数程序员是不太现实的。而在代码写完之后再补上相应的文档则是一件非常常见的做法。Doxygen 就能很好的帮你做好这件事件,在你的代码按照Doxygen 的格式写好注释后,几分钟Doxygen 就能够很快地为你生成文档。最近要使用Doxygen 也是因为代码变多后,之前写的函数往往名字都不记得了,如果能有一份文档查询相应的函数会非常方便。(值得一提的是Hadoop 支持了Doxygen 文档的生成)

一、安装

在官网下载Doxygen ,然后./config 生成Makefile 文件,make, make install 即可。需要注意的是:

先需要下载好相应的工具:

  1. GNU 工具flex,bison,GNU make 和strip
  2. 需要perl 生成makefile 文件
  3. 需要UNIX tools 的常用工具:sed, date, find, uname, mv, cp, cat, echo, tr, cd, 和 rm

如果你下载的是安装文件(bin),./configure 不会检查这些工具是否缺失,因为如果缺少了这些文件则会报make 中间过程的错误。但如果下载的是源代码文件(src),其中的./configure 会检查相应的工具是否存在,因为建议下载源代码文件编译后安装。

 

二、Doxygen 配置

进入所在项目的目录后,可以使用doxygen -g 生成配置文件Doxygen,打开该目录下的配置文件Doxyfile,有相关的配置信息:

DOXYFILE_ENCODING      = UTF-8      文档编码方式,GB2312可以更好支持中文

PROJECT_NAME                  =                  项目名称

PROJECT_NUMBER             =                 项目编号

PROJECT_BRIEF                  =                 项目简介

PROJECT_LOGO                   =                 项目LOGO

OUTPUT_DIRECTORY         = doc/         项目文档默认位置

CREATE_SUBDIRS               = NO           创建4096 个子目录保存生成文件,适合大项目

OUTPUT_LANGUAGE          = English     语种,Chinese/Chinese-Traditional 也支持

BRIEF_MEMBER_DESC     = YES          YES(默认)将每个函数或者类的简述加在前面

OPTIMIZE_OUTPUT_FOR_C  = NO     只是C 文档选YES

QUIET                                     = YES          如果出现错误,不中断

FILE_PATTERNS                   = *.h           只对.h 头文件生成

RECURSIVE                            = YES         递归虚幻当前目录子目录

GENERATE_LATEX               = NO          不生成latex 文档

GENERATE TREEVIEW       =ALL          文档左侧生成一个侧栏显示类、文件和包关系

配置完后直接 doxygen 就可以生成对应文档了。或者doxygen confile 针对配置问津confile 生成文档。

 

三、为代码撰写评论(comments)

  总体来说有三类评论(comments):详细评论(detailed comments);简要评论(brief comments)和函数内评论(body comments)。对于不同类型的评论有不同的方法。

1、详细评论

下面是详细评论的几种方法

/**
 * ... comments ...
 */
/*!
 * ... comments ...
 */
/*!
 ... comments ...
*/
///
/// ... comments ...
///
//!
//!... comments ...
//!

2、简要评论

下面是几种简要评论的几种方法

/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */
/** Brief description which ends at this dot. Details follow
 *  here.
 */
/// Brief description which ends at this dot. Details follow
/// here.
/// Brief description.
/** Detailed description. */
//! Brief description.

//! Detailed description 
//! starts here.
//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
 */

3、函数内评论

下面是几种函数内评论

int var; /*!< Detailed description after the member */
int var; /**< Detailed description after the member */
int var; //!< Detailed description after the member
         //!< 
int var; ///< Detailed description after the member
         ///< 
int var; //!< Brief description after the member
int var; ///< Brief description after the member
void foo(int v /**< [in] docs for input parameter v. */);

下面是一个完整的例子:

/*! A test class */
class Test
{
  public:
    /** An enum type. 
     *  The documentation block cannot be put after the enum! 
     */
    enum EnumType
    {
      int EVal1,     /**< enum value 1 */
      int EVal2      /**< enum value 2 */
    };
    void member();   //!< a member function.
    
  protected:
    int value;       /*!< an integer value */
};

通过@param 可以在块(函数)注释中添加输入类型和定义, @return 定义返回值

 

四、为html 安装apache

  1. sudo apt-get install apache2
  2. 修改/etc/apache2/apache2.conf 配置文件(可选,参考这里
  3. 修改/etc/apache2/sites-endabled/ 中DocumentRoot 和主目录为自己html 文档生成的地方
  4. sudo service apache2 restart

这样通过网页方式可以查看到自己生成的文档了~~

 

 

参考资料:

【1】Doxygen 配置文件说明

【2】Doxygen 官网

【3】Doxygen 语法

Linux 下使用Doxygen》上有2条评论

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据