chatgpt 软件详细设计文档 Doxygen——根据代码注释生成文档的工具

文章目录

1 简介

是一个可以根据代码注释生成文档的工具，支持HTML、CHM、LaTex等格式。主要支持C语言、语言，还支持C++、Java、C#等语言。

通常我们在写程序时，或多或少都会写上注释，但是对于其它人而言，要直接探索程序里的注释会比较麻烦。大部分有用的注释都是属于对函数、类型等的说明。所以，如果能依据程序本身的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用此程序代码的人而言将会减少许多负担。

2 安装

sudo apt install doxygen
sudo apt install doxygen-gui

其中，使用命令行操作，-gui是的图形用户界面。

3 使用 3.1 注释代码

能识别这几种风格的注释：

/**
 * ... text ...
 */
/*!
 * ... text ...
 */
///
/// ... text ...
///
//!
//!... text ...
//!

文件的开头必须有文件注释，否则该文件不会被识别：

/** @file */ 

结构化命令可以识别代码块的含义，主要包括：

其中，可以替换为@，即class等价于@class。

具体怎么写注释？可以直接看一个使用风格的C++代码文档的例子：

/**
 *  A test class. A more elaborate class description.
 */
 
class Javadoc_Test
{
  public:
 
    /** 
     * An enum.
     * More detailed enum description.
     */
 
    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Javadoc_Test();
 
      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Javadoc_Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Javadoc_Test()
       * @see ~Javadoc_Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;
   
      /** 
       * a public variable.
       * Details.
       */
       int publicVar;
       
      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

单击此处查看由生成的相应HTML文档。

也支持C和等编程语言的注释，用法可以参考此。

3.2 使用生成文档

安装完成和-gui后，在终运行命令启动 GUI。作为初学者，可以先使用 GUI熟悉的使用方法。

的用法参考此链接，主要包括三个步骤：

设置设置

页面包括：

页面包括很多高级的设置，要根据自己的实际需求调整。例如，我在注释项目中的类的私有成员函数时，输出的文档中并没有显示该信息，原因是没有选中下Build中的。

在Run页面点击Run 按钮，窗口会输出日志信息，如果最后显示 has ，则表明运行成功。

最后，点击Show HTML ，会使用浏览器打开将代码文档化的网页。

4 用例 4.1

等开源库很好的使用了，可以直接看文档和代码感受一下：

当然，是一个优秀的开源库，内容多且详细，我们可以根据自己项目的实际情况制定一套规则。

4.2

目前部分代码也使用了，例如：

但是还没完全覆盖整个项目， 6.0计划推出在线的文档，大概率就是用这个工具生成的。

此外，的cyber模块更多的使用了。

cd /apollo/cyber/doxy-docs/
./build_doxy_sphinx.sh

安装相关依赖：

pip install sphinx breathe recommonmark -i https://pypi.tuna.tsinghua.edu.cn/simple

运行脚本：

./build_doxy_sphinx.sh

然后，打开//cyber/doxy-docs/build/html中任意一个html文件即可。

注：这种打开html文件的方法不是很优雅，因为我对的操作还不是很熟悉。

5 参考