doxygen是一种从源代码生成文档的工具，支持多种语言。当然，源代码中需按一定的格式写注释，这些注释的格式也能帮助我们养成很好的注释习惯，可以尝试一下。





  使用doxygen生成文档的方法很简单：



**
  

    $ doxygen -g –s
  

  
  

    $ doxygen
  

</blockquote>



  只需两个简单命令就可以了。





  下面简单说明一下：





  1、在工程目录下输入doxygen –s –g doxyconfig，其中doxyconfig为生成配置的文件名称，可任意指定，如果不指定，默认生成的配置文件为Doxyfile。man手册中没有详细说明选项的意思，这里不妨猜测一下，-s为simple，-g为generate，如果不指定-s，则生成的配置文件大约为63KB，行数约1500左右；反之，则约成10KB，行数约250左右。——此处猜测便根据这些测试而来的。





  2、生成配置文件后，会出现提示信息，大意是说那个配置文件已经生成了，现在编辑它，之后输入doxygen Doxyfile(经实践证明，可以只输入doxygen命令)就可以产生工程的文档了。如果再次使用doxygen生产配置文件，则原来的就配置文件就变成了备份文件，添加后缀名.bak。





  3、根据doxygen要求的注释格式来编写代码的注释，这一步要求比较高，而且工作量比较大。我们在文章后面还要讲解的。





  下面介绍一下如何编辑生成的配置文件，我们以我们的串口程序为例子。





  &nbsp;





  doxygen的配置文件与大多数linux平台的配置文件类似，就是一些关键字与值，配置文件中的值以YES和NO居多。



<blockquote>
  

    DOXYFILE_ENCODING = UTF-8，默认编码为UTF-8，这样可以支持中文。
  

  
  

    PROJECT_NAME = “SerialPort”，项目名称，多个单词需要使用引号(“”)。
  

  
  

    PROJECT_NUMBER = “1.0 beta”，项目版本号。
  

  
  

    OUTPUT_DIRECTORY = serialport-html，输出文档的目录，如果为空，表示在当前目录，建议写上表示本工程的有意义的目录名称，比如我们就指定目录名称为serialport-html。
  

  
  

    OUTPUT_LANGUAGE = English，文档语言，可以指定为Chinese。
  

  
  

    IMAGE_PATH = image_dir，指定图片存放的目录，我们将图片放到当前目录下的image_dir目录中，因为我们的文档会出现测试图片示例。
  

  
  

    HTML_OUTPUT= . ，html输出目录名称，默认为html目录，如果为“.”则表明为上述OUTPUT_DIRECTORY目录。
  

  
  

    GENERATE_LATEX = NO，是否生成LaTeX，默认生成的，但我们不想生成。
  

  
  

    好了，我们需要修改的就这么多，使用上述第2步骤的命令就可以生成一个漂亮的文档了。此外还有一些常用的设置选项。
  

  
  

    INPUT =xxx，代码文件或目录，多个文件(目录)需要以空格隔开，如果不指定，表示当前目录，但是，如果指定目录且当前目录有代码文件的话，需要使用点号(“.”)表示当前目录。
  

  
  

    FILE_PATTERNS=xxx，指定各种文件，我们常用为*.cpp *.c *.h，等等。
  

</blockquote>



  上面基本就是我们常用的了，如果还想更深入了解，请移步到google网站。





  下面就是真正需要花费一定时间的工作：为我们的程序作特定格式的注释。





  doxygen支持多种注释风格，比如JavaDoc风格，它在C语言块注释开始处再添加一个星号(*)构成，如下：



<div>
  

    1.           /**
  

  
  

    2.            * … text …
  

  
  

    3.            */
  

</div>



  Qt风格：



<div>
  ```
1.           /*!

      
      ```
	2.            * ... text ...

  ```
3.            */

    </div>
    
    

      上面两种方式中间的星号(*)是可选的，不过，个人认为添加会更美观一些。
    

    
    

      C++风格的，——就是在C++注释后面再添加“/”：
    

    
    <div>
      ```
	1.           ///

  ```
2.           /// ... text ...

      
      ```
	3.           ///

</div>



  或者是这样：



<div>
  ```
1.           //!

      
      ```
	2.           //!... text ...

  ```
3.           //!

    </div>
    
    

      经测试，实际使用中，如果是单行注释的话，可以使用如下的格式：
    

    
    <div>
      ```
	1.           /** ... text ... */

  ```
2.           /**< ... text ... */

    </div>
    
    

      这些格式会被doxygen文档化，如果不想让它文档化，可以“破坏”这些格式，比如可以使用“正宗”的C/C++注释：
    

    
    <div>
      ```
	1.           /* ... text ... */

  ```
2.           // ... text ...

    </div>
    
    

      上述风格来自doxygen的manual页面，具体地址为：
    

    
    

      [http://www.stack.nl/~dimitri/doxygen/docblocks.html](http://www.stack.nl/~dimitri/doxygen/docblocks.html)
    

    
    

      http://www.stack.nl/~dimitri/doxygen/index.html
    

    
    ```
# 自定义文档首页
# INPUT                  = README.md other_sources
# USE_MDFILE_AS_MAINPAGE = README.md

  下面介绍一下常用doxygen的命令，更多详细使用说明，请参考如下地址：





  [http://www.stack.nl/~dimitri/doxygen/commands.html#cmde](http://www.stack.nl/~dimitri/doxygen/commands.html#cmde)





  doxygen命令以@或开始，两种方式均可以。文中以@标记之。



<blockquote>
  

    @def 宏定义说明
  

  
  

    @fn 函数 函数说明
  

  
  

    @param 参数 参数说明
  

  
  

    @return 返回值说明(出错返回什么值，等等)
  

  
  

    @file 文件名
  

  
  

    @author 作者
  

  
  

    @version 程序版本
  

  
  

    @date 日期
  

  
  

    @note 注解(注意事项，等)
  

  
  

    @warning 警告信息
  

  
  

    @bug bug信息
  

  
  

    @test 测试示例、信息
  

  
  

    @todo 一些未完事宜
  

  
  

    (@bug、@test以及@todo等会出现链接页面)
  

  
  

    上面这样适合在函数、文件前面出现。
  

  
  

    下面为生成特殊字体的命令：
  

  
  

    @a @e @em：其后的单个字(word)表现为斜体，以强调作用。如有多个word的话，使用*xxx xxx*代替。
  

  
  

    @b：其后的word为粗体，多个则使用<b>xxx xxx**。
  

  
  

    @c @p：字体表现为打印机字体，多个则使用<tt>xxx xxx</tt>。
  

</blockquote>



  ` `





  `下面是一些具体的实例。 `





  `在文件开始处的版权声明及其它信息：`



**
  

    /**
  

  
  

    *                      Copyleft (C) 2010  Late Lee
  

  
  

    *        This program is tested on LINUX PLATFORM, WITH GCC 4.x.
  

  
  

    *        The program is distributed in the hope that it will be
  

  
  

    *        useful, but WITHOUT ANY WARRANTY. Please feel free to
  

  
  

    *        use the program, and I feel free to ignore the related
  

  
  

    *        issues. Any questions or suggestions, or bugs, please
  

  
  

    *        contact me at  or e-mail to
  

  
  

    *         if you want to do this.
  

  
  

    * @file   serialport.c
  

  
  

    * @author Late Lee
  

  
  

    * @date   Mon Jan 10 2011
  

  
  

    *
  

  
  

    * @brief  Some utils of the serial port, such as open the port, close
  

  
  

    *         the port and setup the port.
  

  
  

    * @note   This is a note.
  

  
  

    * @warning This is a warning.
  

  
  

    * @bug    This is a bug.
  

  
  

    */
  

</blockquote>



  &nbsp;





  在函数前的注释：





  &nbsp;



<blockquote>
  

    /**
  

  
  

    * open_port – Open a serial port
  

  
  

    *
  

  
  

    * @param port : The port number, eg, open_port(1) will open com1
  

  
  

    *
  

  
  

    * @return Return fd if success, otherwise will return -1 with some msg.
  

  
  

    */
  

</blockquote>



  定义宏使用的注释：



<blockquote>
  

    /**
  

  
  

    * @def error_exit
  

  
  

    * @brief A macro that prints the @a error msg and exit.
  

  
  

    */
  

  
  

    #define error_exit(error)
  

  
  

    do{
  

  
  

    fprintf(stderr, “%sn”, error);
  

  
  

    exit(0);
  

  
  

    } while(0)
  

</blockquote>



  &nbsp;





  &nbsp;





  或者你会说，这样的注释风格太麻烦了！不怕！现在有了跟emacs结合的doxymacs，在emacs中配置了doxymacs，这些注释是十分方便的！比如需要在文件前插入注释，按C-c d i即可，在函数前插入注释，按C-c d f即可，等等。具体的请移步到这里的文章：[http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs-ii](http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs-ii.html)及[http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs](http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs.html)。如果你使用的不是emacs，那Sorry，我也不太会，如果你懂，不妨分享一下。





  这个串口程序的文档已经放到网站上了，这里main.c文件参考页面地址：[http://www.latelee.org/yetanothertest/serialport-html-cn/main_8c.html](http://www.latelee.org/yetanothertest/serialport-html-cn/main_8c.html)





  此外，我们还测试生成中文文档，因此doxygen使用UTF8，因此只要将代码文件保存为utf8编码即可(使用Ultra Edit或notepad++等等编辑器很容易做到)。但这又引出一个问题，gcc并不支持utf8！经过google，发现gcc 4.4.0版本以后已经支持utf8了，因此，为了做这个测试，花了一个小时左右编译、安装高版本的gcc(我们使用4.4.5版本)，结果，这个版本的gcc是支持utf8的。后来，又发现，如果使用“UTF-8 无BOM格式编码”格式保存源文件的话，在原来的gcc下也编译通过。因此如果想在程序中使用中文注释，建议以此格式保存，当然，在系统的locale不是中文的情况下看到的中文是乱码的。





  1、尽信书则不如无书，我们建议各位到实践中试一试，这样学到的知识才是我们自己的，比如，在指定源代码目录中，我的测试文件main.c放在当前目录下，如果不指定“.”的话，doxygen便不会处理该文件，这是网上很多资料没有说明的，因此需要实践才能了解。





  2、我们强烈建议各位到官方网站学习，因为其它地方绝大部分都出自官方网站，manual页面地址是：





  [http://www.stack.nl/~dimitri/doxygen/manual.html](http://www.stack.nl/~dimitri/doxygen/manual.html)