如何让命名空间的通用Doxygen注释单独显示或关联每个结构体？

问题描述 #

在impstrcts.h文件中编写了如下代码：

namespace mynameSpace{

/*!
some doxygen for the collection of label_str, Label_map, big_map
*/

/*!
some doxygen for the label_str
*/
template<template<typename ...> class Tcont, typename... Titem>
struct label_str
{
    Tcont<Titem...> kindA;
};

/*!
* some doxygen commnets for label_map
*/
struct Label_map
{
    label_str<std::map, alpha, beta> al_beta_map;
};

/*!
* some doxygen comments for big_map
*/
struct big_map
{
    Label_map first;
    Label_map second;
};
}

当前针对label_str、Label_map、big_map集合的通用注释仅显示在label_str结构体上，需要实现两种需求之一：

1. 让该通用注释单独显示
2. 让该通用注释出现在命名空间内的每个结构体上

解决方案 #

方案1：让通用注释单独显示（通过分组管理） #

使用Doxygen的@defgroup标记创建结构体集合组，将通用注释放在组说明中，再用@ingroup将每个结构体关联到该组。这样文档中会单独生成一个组条目，通用注释展示在组的描述里，同时每个结构体保留自身注释。

修改后代码：

namespace mynameSpace{

/*!
@defgroup struct_collection 结构体集合
@brief some doxygen for the collection of label_str, Label_map, big_map
*/

/*!
@ingroup struct_collection
some doxygen for the label_str
*/
template<template<typename ...> class Tcont, typename... Titem>
struct label_str
{
    Tcont<Titem...> kindA;
};

/*!
@ingroup struct_collection
* some doxygen commnets for label_map
*/
struct Label_map
{
    label_str<std::map, alpha, beta> al_beta_map;
};

/*!
@ingroup struct_collection
* some doxygen comments for big_map
*/
struct big_map
{
    Label_map first;
    Label_map second;
};
}

方案2：让通用注释出现在每个结构体上（通过注释复制） #

使用Doxygen的@copydoc命令，先给通用注释添加一个锚点标记，再在每个结构体的注释中复制该通用内容。这样每个结构体的文档中都会包含通用注释的内容。

修改后代码：

namespace mynameSpace{

/*!
@anchor structs_common_note
some doxygen for the collection of label_str, Label_map, big_map
*/

/*!
some doxygen for the label_str
@copydoc structs_common_note
*/
template<template<typename ...> class Tcont, typename... Titem>
struct label_str
{
    Tcont<Titem...> kindA;
};

/*!
* some doxygen commnets for label_map
@copydoc structs_common_note
*/
struct Label_map
{
    label_str<std::map, alpha, beta> al_beta_map;
};

/*!
* some doxygen comments for big_map
@copydoc structs_common_note
*/
struct big_map
{
    Label_map first;
    Label_map second;
};
}

内容的提问来源于stack exchange，提问作者Morpheus