How to ensure that the same comment appears for each struct in a namespace using doxygen-CodePudding

I have the following namespace and some code in a file called 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;
};
}

Is there a way I can have the general doxygen comment appear by itself or maybe with every struct in the namespace? Because right now, the some doxygen for the collection of label_str, Label_map, big_map appears only for the label_str struct.

CodePudding user response：

Using the default doxygen configuration file, you can put the common documentation onto some "object" such as a group and use \copydoc to copy it. For example:

namespace mynameSpace{

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

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

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

/*!
* \brief some doxygen comments for big_map
* \copydoc MyCollection
*/
struct big_map
{
    Label_map first;
    Label_map second;
};
}

The explicit \brief statements were necessary in my tests to ensure that doxygen does not confuse brief with details.

Instead of defining a custom group, you could also simply put the documentation at the namespace mynameSpace and use \copydoc mynameSpace:

/// some doxygen for the collection of label_str, Label_map, big_map
namespace mynameSpace{

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

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

/*!
* \brief some doxygen comments for big_map
* \copydoc mynameSpace
*/
struct big_map
{
    Label_map first;
    Label_map second;
};
}

Unfortunately, there seems to be no way to get the effect of \copydoc somehow automatically. There is something called "member groups" and the configuration variable DISTRIBUTE_GROUP_DOC which can be set to YES (default is NO). They do something that is related to what you want: Every member of a group gets the description of the first member. However, it apparently does not work for structs/classes. And in any case, the members must not be documented otherwise (no automatic merging of documentation even if it were to work for structs/classes).