doxygen总结

一.问题
  1.工程太庞大了:代码行总数:1038099(88.24%);
  2.注释太少了:注释行总数:92759(7.88%);
  3.新员工上手教慢;
  4.维护时发现有些代码作者都看不懂了;
二.思路
  1.增加注释
  2.统一注释格式
  3.抽取注释, 生成文档, 提供给新员工
三.实现
  1. 采用doxygen注释.
  2.每个.h文件的头部,必须添加注释,格式如下:
  /** /file file.h
   * A brief file description.
   * A more elaborated file description.
   */

  3.每个类的声明上方,必须添加注释,格式如下:
  /** /class Test class.h
   *  /brief This is a test class.
   *
   * Some details about the Test class
   */
   class Test
   {
    ...
   };

  4.每个成员变量及成员函数的定义的右边或上方,必须添加注释,格式如下:
  /** Some details about the function open */
  void open();

  5.每个全局函数、全局变量、宏定义的定义的右边或上方,必须添加注释,格式如下:
  /** Some details about the function GlobalFunc*/
  void GlobalFunc();

  6.每个.cpp文件头部,必须添加注释,格式如下:
  /** /file file.cpp
   * A brief file description.
   * A more elaborated file description.
   */

   7.每个函数的实现上方,必须添加注释,格式如下:
  /** /brief A member function.
   *  /param c a character.
   *  /param n an integer.
   *  /exception std::out_of_range parameter is out of range.
   *  /return a character pointer.
   */
   const char *member(char,int) throw(std::out_of_range)
   {
   }

   8.每个枚举定义必须添加注释,格式如下:
      /** Another enum, with inline docs */
      enum AnotherEnum
      {
        V1, //< value 1
        V2  //< value 2
      };

  9.实现代码中关键的代码必须加注释,格式如下:
  {
    //some details about the next line code
    if (Button1->Enabled)
    {
    }
  }
 
  10. 必须实行代码检查机制.

注:
什么是doxygen呢？下面的介绍录自doxygen的网页：
“doxygen是一种用于C++、IDL（Corba、Microsoft和KDE-2 DCOP风格）和C的文档系统。它可以通过三种方式来帮助你：
1. 它可以从一组标有文档的源文件中生成在线文档浏览器（HTML格式），以及/或者离线参考手册（LATEX格式）。同时还支持生成RTF（MS-Word）、Postscript、超链接PDF、压缩HTML和UNIX man页面格式的输出。文档是从源文件中直接提取的，从而十分容易保持文档和源码的一致。
2. 可配置doxygen，用以从没有标注文档的源文件中提取代码结构。这对于要在大量源文件中快速地找到所需的东西来说是非常有用的。通过include依赖图、继承图和协作图等手段（它们都是自动生成的），可以使不同成分之间的关系可视化。
3. 你甚至还可以“滥用”doxygen，创建普通文档。”