Doxygen学习笔记

最新推荐文章于 2024-05-14 00:04:14 发布

mingshili

最新推荐文章于 2024-05-14 00:04:14 发布

阅读量1k

点赞数 1

分类专栏：代码规范编程工具文章标签： doxygen python c++

本文链接：https://blog.csdn.net/mingshili/article/details/112341180

版权

代码规范同时被 2 个专栏收录

8 篇文章 0 订阅

订阅专栏

编程工具

1 篇文章 0 订阅

订阅专栏

文章目录

1. Doxygen基本介绍
2. Doxygen 下载安装
- 2.1 Git方式安装（源码）
- 2.1 安装包方式安装
3. Doxygen使用
4. 配置doxygen
5. 开始正题-要生成doxygen文档，该怎么写注释
10. special commands特殊格式块儿写法
- 10.1 例如甘特图

1. Doxygen基本介绍

Doxygen是从代码中生成document的工具；支持的语言有：C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL and to some extent D. 【如，opencv官网，TI SDK中的一些html，都是采用这个工具生成，在学习API时很方便】

支持在RTF（MS Word）、PostScript、超链接PDF、压缩HTML和Unix手册页中生成输出
Doxygen还可以通过include依赖图、继承图和协作图来可视化各个元素之间的关系，这些图都是自动生成的
还使用doxygen创建普通文档

2. Doxygen 下载安装

2.1 Git方式安装（源码）

git clone https://github.com/doxygen/doxygen.git
cd doxygen
#######################
mkdir build
cd build
cmake -G "Unix Makefiles" ..
make
######################
make install

2.1 安装包方式安装

doxygen下载页: 可以下载mac, windows, linux等系统安装包
doxygen-1.9.0 下载链接
具体安装方式：链接

3. Doxygen使用

3.1 第1步，确认支持你使用的语言

确认自己的预研是否doxygen支持；主要支持：C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Fortran and D；当然特殊语言还需要再配置；

3.2 第2步创建一个配置文件，对doxygen配置

doxygen通过配置文件设置所有的配置，最好每一个工程配置一个configure 文件。

执行下面命令获取一个config模板，这个模板的风格类似makefile

doxygen -g <config-file>

解析对照表，因为doxygen是面向C/C++语言解析的，所以当解析其他语言时，都会有C/C++对应后缀的文件与之对应；
doxygen官网编程语言后缀名对照图

3.3 第3步产生documentation

配置好config 文件后，就可以执行下面语句获取documentation了

doxygen <config-file>

根据config文件，会产生相应的html, rtf,latex,xml, man 或者doxbook.
当然可以配置不同格式的输出：：

The format specific directory within the output directory can be 
selected using the HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, XML_OUTPUT, 
MAN_OUTPUT, and DOCBOOK_OUTPUT. tags of the configuration file

3.4 第4步记录来源

如果配置文件中EXTRACT_ALL =NO ，则仅仅会记录实体；然而对于类成员，类，命名空间等对象，我们想根据自己的需求进行选择性地记录呢？则需要以下两种配置方式（选择哪一种，根据实际需要）：
- 在这些对象中放置一个特殊文档块；具体怎么写这些特殊文档块，可以参考链接：；【好处：不用重命名实体】
- 将一个特殊的文档块放在其他地方（另一个文件或其他位置），并在文档块中放置一个结构化命令。结构化命令将文档块链接到可以被文档化的特定实体（例如，成员、类、命名空间或文件）。

4. 配置doxygen

有两种方式，文本编辑，还有UI编辑

简单配置说明：

For a small project consisting of a few C and/or C++ source and header files, you can leave INPUT tag empty and doxygen will search for sources in the current directory.

If you have a larger project consisting of a source directory or tree you should assign the root directory or directories to the INPUT tag, and add one or more file patterns to the FILE_PATTERNS tag (for instance *.cpp *.h). Only files that match one of the patterns will be parsed (if the patterns are omitted a list of typical patterns is used for the types of files doxygen supports). For recursive parsing of a source tree you must set the RECURSIVE tag to YES. To further fine-tune the list of files that is parsed the EXCLUDE and EXCLUDE_PATTERNS tags can be used. To omit all test directories from a source tree for instance, one could use:

EXCLUDE_PATTERNS = */test/*

5. 开始正题-要生成doxygen文档，该怎么写注释

5.1 类C语言的注释编写（如C/C++/C#/Objective-C/PHP/Java）

5.1.1 注释块儿的写法：

// ================= 1)  正常写法
/**
  * ... text ...
  */
  
// ================    2) ‘感叹号’
/*!
  * ... text ...
  */
// ================     3) 可以没有中间的 ·*·
/*!
 ... text ...
*/

// ================       4)  ‘ /// 方式 ’
///
/// ... text ...
///
或者
//!
//!... text ...
//!

5.1.2. 为了让注释更加明显，可以用一下写法，并且配置中JAVADOC_BANNER=YES**

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

/
/// ... text ...
/

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

比如：源代码情况

及对应的doxygen的展示情况
对应的doxygen格式

5.1.3 简短描述的写法

用\brief

/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */

用JAVADOC_AUTOBRIEF =YES in the configuration file,会自动将第一个句号"."前的一句话作为brief description.

/** Brief description which ends at this dot. Details follow
 *  here.
 */
 
/// Brief description which ends at this dot. Details follow
/// here.

A third option is to use a special C++ style comment which does not span more than one line.

1)
/// Brief description.
/** Detailed description. */

2) 
//! Brief description.

//! Detailed description 
//! starts here.

多个详细描述时

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

在头文件可以简述函数功能，在具体的实现文件可以详细描述

5.1.4 对members进行描述(如struct, union, class, or enum)

添加详细的描述
int var; /*!< Detailed description after the member */  
Or
int var; /**< Detailed description after the member */  Qt style

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

对于函数的参数的注释，可以如下写法，并且可以标注是传入还是传出函数

[in], [out], [in,out] 表示传入，传出，即传入又传出
void foo(int v /**< [in] docs for input parameter v. */);

示例：
源代码
示例形式

【注意】These blocks can only be used to document members and parameters. They cannot be used to document files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural commands mentioned in the next section (like \class) are not allowed inside these comment blocks

示例2，自动brief

/**
 *  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);
};

效果图

5.1.5 将注释写到一个统一的地方

\class to document a Class
\struct to document a C-struct. 
• \union to document a union. 
• \enum to document an enumeration type. 
• \fn to document a function. 
• \var to document a variable or typedef or enum value. 
• \def to document a #define. 
• \typedef to document a type definition. 
• \file to document a file. 
• \namespace to document a namespace. 
• \package to document a Java package. 
• \interface to document an IDL interface.

更多的特殊命令见连接：special commands

先看一个示例：

/*! \file structcmd.h
    \brief A Documented file.
    
    Details.
*/
 
/*! \def MAX(a,b)
    \brief A macro that returns the maximum of \a a and \a b.
   
    Details.
*/
 
/*! \var typedef unsigned int UINT32
    \brief A type definition for a .
    
    Details.
*/
 
/*! \var int errno
    \brief Contains the last error code.
 
    \warning Not thread safe!
*/
 
/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.
 
    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/
 
/*! \fn int close(int fd)
    \brief Closes the file descriptor \a fd.
    \param fd The descriptor to close.
*/
 
/*! \fn size_t write(int fd,const char *buf, size_t count)
    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    \param fd The descriptor to write to.
    \param buf The data buffer to write.
    \param count The number of bytes to write.
*/
 
/*! \fn int read(int fd,char *buf,size_t count)
    \brief Read bytes from a file descriptor.
    \param fd The descriptor to read from.
    \param buf The buffer to read into.
    \param count The number of bytes to read.
*/
 
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

![效果图(https://img-blog.csdnimg.cn/20210113214815947.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmdzaGlsaQ==,size_16,color_FFFFFF,t_70)

5.1.6 对于不能解析的文件

If you have a file that doxygen cannot parse but still would like to document it, you can show it as-is using \verbinclude, e.g.

/*! \file myscript.sh
 *  Look at this nice script:
 *  \verbinclude myscript.sh
 */

5.2 python的注释编写

5.2.1 两种写法

"""@package docstring
Documentation for this module.
 
More details.
"""
 
def func():
    """Documentation for a function.
 
    More details.
    """
    pass
 
class PyClass:
    """Documentation for a class.
 
    More details.
    """
   
    def __init__(self):
        """The constructor."""
        self._memVar = 0;
   
    def PyMethod(self):
        """Documentation for a method."""
        pass

效果图
第2种

## @package pyexample
#  Documentation for this module.
#
#  More details.
 
## Documentation for a function.
#
#  More details.
def func():
    pass
 
## Documentation for a class.
#
#  More details.
class PyClass:
   
    ## The constructor.
    def __init__(self):
        self._memVar = 0;
   
    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass
     
    ## A class variable.
    classVar = 0;
 
    ## @var _memVar
    #  a member variable

5.2.2 python docstring与doxygen的选择

如果用doxygen的special commands，则用’’’!, 带感叹号；
否则用’’'的时候doxygen的special commands会失效

5.2.3 注意设置OPTIMIZE_OUTPUT_JAVA = YES

因为python更像java而不是C/C++; 所以需要在配置文件里设置OPTIMIZE_OUTPUT_JAVA = YES。

5.3 注释块剖析

doxygen1.8.0之后，支持markdown的语法的注释；需要安装markdown Extra.
而且对于XML，HTML格式的也会有支持。

10. special commands特殊格式块儿写法

10.1 例如甘特图

也就是在在吗注释中写入甘特图等一些列图表明程序执行逻辑，而doxygen会根据相应的语法生成相应的甘特图等一系列图在生成的doc中展示。
具体语法可以访问：https://plantuml.com/zh/ 没有www；

网页主页

@startuml
用户 -> 认证中心: 登录操作
认证中心 -> 缓存: 存放(key=token+ip,value=token)token

用户 <- 认证中心 : 认证成功返回token
用户 -> 认证中心: 下次访问头部携带token认证

认证中心 <- 缓存: key=token+ip获取token
其他服务 <- 认证中心: 存在且校验成功则跳转到用户请求的其他服务
其他服务 -> 用户: 信息
@enduml

效果图