我如何记录以使文档适用于类成员而不是匿名类型？

Question

请考虑以下示例。

/// \addtogroup api Foo Group
/// @{

/**
 * This class is well-documented.
 */
struct ThreadContext {
    /// Storage for the ThreadInvocation object that contains the function and
    /// arguments for a new thread.
    struct alignas(CACHE_LINE_SIZE) {
        /// This data is glorious.
        char data[CACHE_LINE_SIZE];
    } threadInvocation;
};
/// @}

当我对此运行doxygen时，我收到以下警告。

Doxygen/Main.h:13: warning: Member threadInvocation (variable) of class ThreadContext is not documented.

以Storage for the ...开头的注释应该引用threadInvocation对象，但doxygen认为它指的是匿名的struct。

我如何告诉doxygen我希望文档引用threadInvocation成员？

Answer 1

在深入挖掘doxygen documentation之后，我发现doxygen实际上允许在几乎任何地方记录大多数代码。为了记录threadInvocation并避免不记录匿名struct的警告，我不得不写这样的代码。

/// \addtogroup api Foo Group
/// @{

/**
 * This class is well-documented.
 */
struct ThreadContext {
    /// \var threadInvocation
    /// Storage for the ThreadInvocation object that contains the function and
    /// arguments for a new thread.

    /// \cond SuppressDoxygen
    struct alignas(CACHE_LINE_SIZE) {
        /// This data is glorious.
        char data[CACHE_LINE_SIZE];
    }
    /// \endcond
    threadInvocation;
};
/// @}