1 doxygen 初步入门

最新推荐文章于 2024-05-15 06:07:41 发布

lujiangyuan

最新推荐文章于 2024-05-15 06:07:41 发布

阅读量503

点赞数

分类专栏： doxygen 文章标签： doxygen

本文链接：https://blog.csdn.net/lujiangyuan/article/details/104673305

版权

doxygen 专栏收录该内容

9 篇文章 1 订阅

订阅专栏

1 支持的语言

Doxygen 支持C，C ++，C＃，Objective-C，IDL，Java，VHDL，PHP，Python，Tcl，Fortran和D语言。

我是做嵌入式开发的，下面的介绍主要侧重在C语言方面。

2 注释的样式

2.1 Javadoc样式

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

Javadocs是Stm32hal 库中使用的格式

stm32使用的格式如下：

/**
  ******************************************************************************
  * @file    stm32f7xx_hal_pcd_ex.c
  * @author  MCD Application Team
  * @brief   PCD Extended HAL module driver.
  *          This file provides firmware functions to manage the following
  *          functionalities of the USB Peripheral Controller:
  *           + Extended features functions
  *
  ******************************************************************************
  * @attention
  *
  * <h2><center>&copy; Copyright (c) 2017 STMicroelectronics.
  * All rights reserved.</center></h2>
  *
  * This software component is licensed by ST under BSD 3-Clause license,
  * the "License"; You may not use this file except in compliance with the
  * License. You may obtain a copy of the License at:
  *                        opensource.org/licenses/BSD-3-Clause
  *
  ******************************************************************************
  */

keil arm风格

/**************************************************************************//**
 * @file     cmsis_armcc.h
 * @brief    CMSIS compiler ARMCC (Arm Compiler 5) header file
 * @version  V5.0.4
 * @date     10. January 2018
 ******************************************************************************/
/*
 * Copyright (c) 2009-2018 Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the License); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

2.2 Qt样式

使用Qt样式如下，在之后加感叹号

/ *！
 * ...文字... 
 * /

中间的*是可选的，如下格式也可以：

/ *！
 ...文字... 
* /

2.3 C++注释行块

加不加！都可以

/// 
/// ...文字... 
///

要么

//！
//！...文本... 
//！

2.4 有些人希望注释块在文档中更明显，可以使用下面的方式

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

注意要使用两个//

也可以这样

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

还可以这样

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

javadoc格式如下

/**
 * A brief history of JavaDoc-style (C-style) comments.
 *
 * This is the typical JavaDoc-style C-style comment. It starts with two
 * asterisks.
 *
 * @param theory Even if there is only one possible unified theory. it is just a
 *               set of rules and equations.
 */
void cstyle( int theory );

 
/*******************************************************************************
 * A brief history of JavaDoc-style (C-style) banner comments.就是多烧面一行*。
 *
 * This is the typical JavaDoc-style C-style "banner" comment. It starts with
 * a forward slash followed by some number, n, of asterisks, where n > 2. It's
 * written this way to be more "visible" to developers who are reading the
 * source code.
 *
 * Often, developers are unaware that this is not (by default) a valid Doxygen
 * comment block!
 *
 * However, as long as JAVADOC_BLOCK = YES is added to the Doxyfile, it will
 * work as expected.
 *
 * This style of commenting behaves well with clang-format.
 *
 * @param theory Even if there is only one possible unified theory. it is just a
 *               set of rules and equations.
 ******************************************************************************/
void javadocBanner( int theory );
 
/***************************************************************************//**
 * A brief history of Doxygen-style banner comments.
 *
 * This is a Doxygen-style C-style "banner" comment. It starts with a "normal"
 * comment and is then converted to a "special" comment block near the end of
 * the first line. It is written this way to be more "visible" to developers
 * who are reading the source code.
 * This style of commenting behaves poorly with clang-format.
 *
 * @param theory Even if there is only one possible unified theory. it is just a
 *               set of rules and equations.
 ******************************************************************************/
void doxygenBanner( int theory )

2.5 组合使用

1 可以将\brief 与上述一起使用

开始一段作为简短说明的段落。对于类和文件，简要说明将在列表中以及文档页面的开始使用。对于班级和文件成员，简要说明将放置在成员的声明中，并放在详细说明之前。简短描述可能会跨越几行（尽管建议保持简短！）。当遇到空白行或其他分段命令时，简短描述将结束。如果\brief存在多个命令，它们将被合并。有关示例

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

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

2 C++风格

/// Brief description.
/** Detailed description. */

//! Brief description.

//! Detailed description 
//! starts here.

3 下面这个是arm风格的风格。

/**
  \brief   Rotate Right with Extend (32 bit)
  \details Moves each bit of a bitstring right by one bit.
           The carry input is shifted in at the left end of the bitstring.
  \param [in]    value  Value to rotate
  \return               Rotated value
 */

/**
  \fn          uint32_t crc32_data (const uint8_t *data, uint32_t len)
  \brief       Calculate standard 32-bit Ethernet CRC.
  \param[in]   data  Pointer to buffer containing the data
  \param[in]   len   Data length in bytes
  \return      Calculated CRC value
*/

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

hal库里面使用方式

/**
  * @brief Independent WATCHDOG
  */

typedef struct
{
  __IO uint32_t KR;   /*!< IWDG Key register,       Address offset: 0x00 */
  __IO uint32_t PR;   /*!< IWDG Prescaler register, Address offset: 0x04 */
  __IO uint32_t RLR;  /*!< IWDG Reload register,    Address offset: 0x08 */
  __IO uint32_t SR;   /*!< IWDG Status register,    Address offset: 0x0C */
  __IO uint32_t WINR; /*!< IWDG Window register,    Address offset: 0x10 */
} IWDG_TypeDef;

keil arm文件的使用方式

/// BSD message header structure.
typedef struct msghdr {
  void    *msg_name;                    ///< Optional pointer to source address
  uint32_t msg_namelen;                 ///< Size of address buffer
  IOVEC   *msg_iov;                     ///< An array of iovec buffers for the message
  int32_t  msg_iovlen;                  ///< Number of elements in msg_iov
  void    *msg_control;                 ///< Ancillary data
  uint32_t msg_controllen;              ///< Ancillary data buffer length
  int32_t  msg_flags;                   ///< Flags on received message
} MSGHDR;

4 注释块的用法

## 4.1

/*! A test class */
 
class Afterdoc_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 */
};

/*! A test class */

与之前变量定义

/*!< IWDG Key register, Address offset: 0x00 */

多了一个<

多< 表示成员在注释之前

没有<表示成员在注释之后

Warnings:

这些注释块只能用于文档的成员和参数。他们不能使用在file，classes，unions，structs，groups，namesapce，enums。此外，这些注释块中不允许使用下一节中提到的结构命令，比如说\class.

4.2 Qt C++ style

//!  A test class. 
/*!
  A more elaborate class description.
*/
 
class QTstyle_Test
{
  public:
 
    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();
 
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa 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);
};

单击此处以获取doxygen生成的相应HTML文档。

简短描述包含在类，名称空间或文件的成员概述中，并使用小斜体字体打印（可以通过在配置文件中将Brief_MEMBER_DESC设置为来隐藏此描述NO）。默认情况下，简短描述成为详细描述的第一句话（但是可以通过将REPEAT_BRIEF标记设置为来更改NO）。对于Qt样式，简要说明和详细说明都是可选的。

默认情况下，Javadoc样式文档块的行为与Qt样式文档块的行为相同。但是，这与Javadoc规范不符，在Javadoc规范中，文档块的第一句话会自动视为简要说明。要启用此行为，您应该在配置文件中将JAVADOC_AUTOBRIEF设置为YES。如果启用此选项，并且想在句子中间放置一个点而不结束它，则应在其后放置一个反斜杠和一个空格。这是一个例子：

 /** Brief description (e.g.\ using only a few words). Details follow. */

这是与上述代码相同的代码，这次使用Javadoc样式并将JAVADOC_AUTOBRIEF设置为YES进行记录：

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

单击此处以获取doxygen生成的相应HTML文档。

类似地，如果希望将Qt样式文档块的第一句话自动视为简要说明，则可以在配置文件中将QT_AUTOBRIEF设置为YES。

在上一节中的示例中的注释块总是位于前面一个文件，类或命名空间的声明或定义，或者在前面或后面的成员之一。尽管这通常很舒适，但有时可能有理由将文档放在其他地方。为了记录文件，这甚至是必需的，因为没有诸如“在文件前面”之类的东西。

Doxygen允许您将文档块放置在几乎任何地方（例外是在函数体内或在普通C样式注释块内）。

不将文档块直接放在项目之前（或之后）而需要付出的代价是，需要
在文档块中放置结构化命令，这会导致信息重复。因此，实践中应避免使用结构命令，除非其他要求迫使您这样做。

结构化命令（与所有其他命令一样）以反斜杠（）开头\，或者@如果您更喜欢Javadoc样式，则以符号（）开头，后跟命令名称和一个或多个参数。例如，如果要Test在上面的示例中记录该类，则还可以在doxygen读取的输入中放置以下文档块：

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

在此，特殊命令\class用于指示注释块包含该类的文档Test。其他结构命令是：

\struct 记录C结构。
\union 记录工会。
\enum 记录枚举类型。
\fn 记录功能。
\var 记录变量或typedef或枚举值。
\def 记录#define。
\typedef 记录类型定义。
\file 记录文件。
\namespace 记录命名空间。
\package 记录Java包。
\interface 记录IDL接口

有关这些命令和许多其他命令的详细信息，请参见“ 特殊命令”部分。

Attention

让我们重复一下，因为它经常被忽略：要记录全局对象（函数，typedef，枚举，宏等），必须记录定义它们的文件。换句话说，此文件中至少必须有一行。

/*! \file */

或

/** @file */

这是一个structcmd.h使用结构命令记录的名为C的头文件的示例：

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

单击此处以获取doxygen生成的相应HTML文档。

因为上面示例中的每个注释块都包含一个结构命令，所以所有注释块都可以移动到另一个位置或输入文件（例如源文件），而不会影响生成的文档。这种方法的缺点是原型是重复的，因此所有更改都必须进行两次！因此，您应该首先考虑是否确实需要这样做，并尽可能避免使用结构性命令。我经常收到在函数前面的注释块中包含\ fn命令的示例。显然，这是\ fn命令多余并且只会导致问题的情况。

当您将一个注释块在一个文件具有以下扩展名的一个.dox，.txt或.doc则Doxygen的将隐藏在文件列表中该文件。

如果您有doxygen无法解析但仍要记录的文件，则可以使用\ verbinclude将该文件原样显示，例如

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

确保该脚本在INPUT中明确列出，或者确保FILE_PATTERNS包含.sh扩展名，并且该脚本可以在通过EXAMPLE_PATH设置的路径中找到。

注释块的剖析

上一节的重点是如何使doxygen知道代码中的注释，它解释了简短描述和详细描述之间的区别以及结构命令的使用。

在本节中，我们将讨论注释块本身的内容。

Doxygen支持各种格式的注释格式。

最简单的形式是使用纯文本。这将按原样显示在输出中，是简短说明的理想选择。

对于更长的描述，您通常会发现需要更多的结构，例如逐字记录的文本，列表或简单的表格。为此，doxygen支持Markdown语法，包括Markdown Extra扩展的一部分。

Markdown的设计使其非常易于读写。其格式受纯文本邮件启发。Markdown适用于简单的通用格式，例如项目的简介页。Doxygen还支持直接读取markdown文件。有关更多详细信息，请参见Markdown支持一章。

对于编程语言特定的格式，doxygen在Markdown格式的基础上有两种形式的附加标记。

Javadoc喜欢标记。有关doxygen支持的所有命令的完整概述，请参见特殊命令。
C＃标准中指定的XML标记。有关doxygen支持的XML命令，请参见XML命令。

如果这还不够的doxygen也支持一个子集的的HTML标记语言。

转到下一部分或返回索引。

lujiangyuan

关注

0
点赞
踩
4

收藏

觉得还不错? 一键收藏
0
评论
1 doxygen 初步入门

1 支持的语言Doxygen 支持C，C ++，C＃，Objective-C，IDL，Java，VHDL，PHP，Python，Tcl，Fortran和D语言。我是做嵌入式开发的，下面的介绍主要侧重在C语言方面。2 注释的样式2.1 Javadoc样式/ ** * ...text... * /Javadocs是Stm32hal 库中使用的格式stm32使用的格式如下：/**...
复制链接

扫一扫