2 doxygen list grouping_doxygen group嵌套-优快云博客

本文链接：https://blog.youkuaiyun.com/lujiangyuan/article/details/104673360

1 清单

Doxygen提供了多种创建项目列表的方法。

1.1使用破折号

通过在行的开头放置多个与列对齐的减号（-），将自动生成项目符号列表。除了减号，还可以使用加号（+）或星号（*）。

带编号的列表也可以通过使用减号，后跟哈希或使用数字后跟点的方式生成。

列表的嵌套是允许的，并且基于项目的tab。

这是一个例子

  /*! 
   *  A list of events:
   *    - mouse events
   *         -# mouse move event
   *         -# mouse click event\n
   *            More info about the click event.
   *         -# mouse double click event
   *    - keyboard events
   *         1. key down event
   *         2. key up event
   *
   *  More text here.
   */

结果将是：

事件列表：

鼠标事件
1. 鼠标移动事件
2. 鼠标单击事件
  有关单击事件的更多信息。
3. 鼠标双击事件
键盘事件
1. 按键事件
2. 按键事件

更多文字在这里。

如果使用选项卡在列表中缩进，请确保将配置文件中的TAB_SIZE设置为正确的选项卡大小。

您可以通过开始一个新段落或通过在与要结束的列表相同的缩进级别的空行上放置一个点（。）来结束列表。

这是一个不言而喻的例子：

/**
 * Text before the list
 * - list item 1
 *   - sub item 1
 *     - sub sub item 1
 *     - sub sub item 2
 *     . 
 *     The dot above ends the sub sub item list.
 *
 *     More text for the first sub item
 *   .
 *   The dot above ends the first sub item.
 *
 *   More text for the first list item
 *   - sub item 2
 *   - sub item 3
 * - list item 2
 * .
 * More text in the same paragraph.
 *
 * More text in a new paragraph.
 */

为了与Qt软件的内部文档工具qdoc和KDoc兼容，doxygen有两个命令可用于创建简单的未嵌套列表。

有关更多信息，请参见\ arg和\ li。

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

2 List

Doxygen具有三种将事物组合在一起的机制。一种机制在全局级别起作用，为每个组创建一个新页面。这些组在文档中称为“模块”。第二种机制在某些复合实体的成员列表中起作用，并称为“成员组”。对于页面，存在第三种分组机制，称为subpaging。

2.1 模组

模块是在单独页面上将事物组合在一起的一种方法。您可以记录整个组以及所有单个成员。组的成员可以是文件，名称空间，类，函数，变量，枚举，类型定义和定义，也可以是其他组。

要定义一个组，您应该将\ defgroup命令放在一个特殊的注释块中。该命令的第一个参数是应该唯一标识组的标签。
第二个参数是应在文档中出现的组的名称或标题。

您可以通过将\ ingroup命令放在其文档块中，使该实体成为特定组的成员。

为避免在每个成员的文档中添加\ ingroup命令，您还可以按组@{前面的打开标记和组@}后面的结束标记将成员分组。标记可以放在组定义的文档中，也可以放在单独的文档块中。

组本身也可以使用这些分组标记嵌套。

当您多次使用同一组标签时，您将收到一条错误消息。如果您不希望doxygen强制使用唯一标签，则可以使用\ addtogroup而不是\ defgroup。可以像\ defgroup一样使用它，但是当已经定义了该组时，它会将现有文档与新文档静默合并。该组的标题对于此命令是可选的，因此您可以使用

/** \addtogroup <label> 
 *  @{
 */
...

/** @}*/

将其他成员添加到在其他位置更详细定义的组中。

请注意，复合实体（例如类，文件和命名空间）可以放入多个组，但是成员（例如变量，函数，typedef和枚举）只能是一个组的成员（此限制是为了避免链接目标不明确）如果成员没有在其类，名称空间或文件的上下文中记录，而仅作为组的一部分可见）。

Doxygen会将成员放入其定义具有最高“优先级”的组中：例如，显式\ ingroup将通过覆盖隐式分组定义@{ @}。具有相同优先级的组定义冲突会触发警告，除非一个定义是针对没有任何明确文档的成员。

下面的示例将VarInA放入组A，并通过将其放入IntVariables组来静默解决IntegerVariable的冲突，因为IntegerVariable的第二个实例是未记录的：

/**
 * \ingroup A
 */
extern int VarInA;

/**
 * \defgroup IntVariables Global integer variables
 * @{
 */

/** an integer variable */
extern int IntegerVariable;

/**@}*/

....

/**
 * \defgroup Variables Global variables
 */
/**@{*/

/** a variable in group A */
int VarInA;

int IntegerVariable;

/**@}*/

所述\ REF命令可以被用来指代的基团。\ ref命令的第一个参数应该是组的标签。要使用自定义链接名称，可以在标签后的双引号中添加链接的名称，如以下示例所示

This is the \ref group_label "link" to this group.

分组定义的优先级是（从最高到最低）：\ ingroup，\ defgroup，\ addtogroup，\ weakgroup。该\ weakgroup命令酷似\ addtogroup优先级较低。添加它是为了允许“惰性”分组定义：您可以在.h文件中使用具有更高优先级的命令来定义层次结构，并在.c文件中定义\ weakgroup，而不必完全复制层次结构。

例：

/** @defgroup group1 The First Group
 *  This is the first group
 *  @{
 */
 
/** @brief class C1 in group 1 */
class C1 {};
 
/** @brief class C2 in group 1 */
class C2 {};
 
/** function in group 1 */
void func() {}
 
/** @} */ // end of group1
 
/**
 *  @defgroup group2 The Second Group
 *  This is the second group
 */
 
/** @defgroup group3 The Third Group
 *  This is the third group
 */
 
/** @defgroup group4 The Fourth Group
 *  @ingroup group3
 *  Group 4 is a subgroup of group 3
 */
 
/**
 *  @ingroup group2
 *  @brief class C3 in group 2
 */
class C3 {};
 
/** @ingroup group2
 *  @brief class C4 in group 2
 */
class C4 {};
 
/** @ingroup group3
 *  @brief class C5 in @link group3 the third group@endlink.
 */
class C5 {};
 
/** @ingroup group1 group2 group3 group4
 *  namespace N1 is in four groups
 *  @sa @link group1 The first group@endlink, group2, group3, group4 
 *
 *  Also see @ref mypage2
 */
namespace N1 {};
 
/** @file
 *  @ingroup group3
 *  @brief this file in group 3
 */
 
/** @defgroup group5 The Fifth Group
 *  This is the fifth group
 *  @{
 */
 
/** @page mypage1 This is a section in group 5
 *  Text of the first section
 */
 
/** @page mypage2 This is another section in group 5
 *  Text of the second section
 */
 
/** @} */ // end of group5
 
/** @addtogroup group1
 *  
 *  More documentation for the first group.
 *  @{
 */
 
/** another function in group 1 */
void func2() {}
 
/** yet another function in group 1 */
void func3() {}
 
/** @} */ // end of group1

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

2.2 Member Groups

如果一个化合物（例如一个类或文件）具有许多成员，则通常需要将它们分组在一起。Doxygen已经在类型和保护级别上自动将事物分组在一起，但是您可能会觉得这还不够，或者默认分组是错误的。例如，因为您感到不同（语法）类型的成员属于同一（语义）组。

成员组由

///@{ 
  ...
///@}

block or a

/**@{*/ 
  ... 
/**@}*/

如果您喜欢C样式的注释，请阻止。请注意，组成员应物理上位于成员组的身体内部。

在块的开始标记之前，可以放置一个单独的注释块。该块应包含@name（或\ name）命令，并用于指定组的标题。可选地，注释块还可以包含有关该组的更详细的信息。

不允许嵌套成员组。

如果类内成员组的所有成员都具有相同的类型和保护级别（例如，所有成员都是静态公共成员），则整个成员组将显示为类型/保护级别组的子组（该组显示为例如“静态公众成员”部分的小节）。如果两个或多个成员具有不同的类型，则该组将与自动生成的组处于同一级别。如果要强制某个类的所有成员组都位于顶层，则应在该类的文档中放置一个\ nosubgrouping命令。

例：

/** A class. Details */
class Memgrp_Test
{
  public:
    ///@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    ///@}
 
    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};
 
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
 
/** @name Group2
 *  Description of group 2. 
 */
///@{
/** Function 2 in group 2. Details. */
void Memgrp_Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Memgrp_Test::func1InGroup2() {}
///@}
 
/*! \file 
 *  docs for this file
 */
 
//!@{
//! one description for all members of this group 
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
#define A 1
#define B 2
void glob_func();
//!@}

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

在这里，Group1显示为“公共成员”的子部分。Group2是一个单独的部分，因为它包含具有不同保护级别（即公共和受保护）的成员。

2.3 分包

可以使用\ page和\ mainpage命令将信息分组为页面。通常，这将导致页面列表平坦，其中“主”页面是列表中的第一页。

与使用部分模块中描述的方法添加结构相比，使用\ subpage命令向页面添加其他结构通常更为自然和方便。

对于页面A，\ subpage命令将链接添加到另一个页面B，同时使页面B成为A的子页面。这具有将两个组GA和GB组成的作用，其中GB是GA的一部分，而页面A是放在GA组中，而页面B放在GB组中。

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

3 stm32 hal 中用法

/** @addtogroup STM32F7xx_HAL_Driver
  * @{
  */

	/** @addtogroup GPIO
	  * @{
	  */ 

/* Exported types ------------------------------------------------------------*/
		/** @defgroup GPIO_Exported_Types GPIO Exported Types
		  * @{
		  */

/** 
  * @brief GPIO Init structure definition  
  */ 
typedef struct
{

  uint32_t Alternate;  /*!< Peripheral to be connected to the selected pins. 
                            This parameter can be a value of @ref GPIO_Alternate_function_selection */
}GPIO_InitTypeDef;


		/**
		  * @}
		  */

/* Exported constants --------------------------------------------------------*/

		/** @defgroup GPIO_Exported_Constants GPIO Exported Constants
		  * @{
		  */ 

			 /** @defgroup GPIO_pull_define GPIO pull define
			   * @brief GPIO Pull-Up or Pull-Down Activation
			   * @{
			   */  
			#define  GPIO_NOPULL        ((uint32_t)0x00000000U)   /*!< No Pull-up or Pull-down activation  */
			#define  GPIO_PULLUP        ((uint32_t)0x00000001U)   /*!< Pull-up activation                  */
			#define  GPIO_PULLDOWN      ((uint32_t)0x00000002U)   /*!< Pull-down activation                */
			/**
			  * @}
			  */
  
		/**
		  * @}
		  */

/* Exported macro ------------------------------------------------------------*/
		/** @defgroup GPIO_Exported_Macros GPIO Exported Macros
		  * @{
		  */

		/**
		  * @brief  Generates a Software interrupt on selected EXTI line.
		  * @param  __EXTI_LINE__ specifies the EXTI line to check.
		  *          This parameter can be GPIO_PIN_x where x can be(0..15)
		  * @retval None
		  */
		#define __HAL_GPIO_EXTI_GENERATE_SWIT(__EXTI_LINE__) (EXTI->SWIER |= (__EXTI_LINE__))
		/**
		  * @}
		  */

/* Include GPIO HAL Extension module */
#include "stm32f7xx_hal_gpio_ex.h"

/* Exported functions --------------------------------------------------------*/
		/** @addtogroup GPIO_Exported_Functions
		  * @{
		  */

			/** @addtogroup GPIO_Exported_Functions_Group1
			  * @{
			  */
			/* Initialization and de-initialization functions *****************************/
			void  HAL_GPIO_Init(GPIO_TypeDef  *GPIOx, GPIO_InitTypeDef *GPIO_Init);
			void  HAL_GPIO_DeInit(GPIO_TypeDef  *GPIOx, uint32_t GPIO_Pin);
			/**
			  * @}
			  */

			/** @addtogroup GPIO_Exported_Functions_Group2
			  * @{
			  */
			/* IO operation functions *****************************************************/
			GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin);

			/**
			  * @}
			  */ 

		/**
		  * @}
		  */ 
/* Private types -------------------------------------------------------------*/
/* Private variables ---------------------------------------------------------*/
/* Private constants ---------------------------------------------------------*/
		/** @defgroup GPIO_Private_Constants GPIO Private Constants
		  * @{
		  */

		/**
		  * @}
		  */

/* Private macros ------------------------------------------------------------*/
		/** @defgroup GPIO_Private_Macros GPIO Private Macros
		  * @{
		  */
		#define IS_GPIO_PIN_ACTION(ACTION) (((ACTION) == GPIO_PIN_RESET) || ((ACTION) == GPIO_PIN_SET))
		#define IS_GPIO_PULL(PULL) (((PULL) == GPIO_NOPULL) || ((PULL) == GPIO_PULLUP) || \
		                            ((PULL) == GPIO_PULLDOWN))
		/**
		  * @}
		  */

/* Private functions ---------------------------------------------------------*/
		/** @defgroup GPIO_Private_Functions GPIO Private Functions
		  * @{
		  */

		/**
		  * @}
		  */

	/**
	  * @}
	  */ 

/**
  * @}
  */