Doxygen: group data structures on file level

Question

I would like to use the Doxygen grouping mechanism for data structures. I'm already using it for functions and it works well so far. What I've experienced so far fits to the documentation regarding member groups of a single type (e.g. function only) or mixed type (e.g. typedefs and functions).

Now I tried to extend these member groups with data structures, and this fails exceptionally. Data structures are always a top section on its own. My tries so far:

1. Put a data structures definition inside an existing mixed type member group. -> Data structure is still documented in a separate top level section.

/**
 * \file doxytest.h
 */

/**
 * \name Iteration API
 * \brief Some documentation. Group will be on top level.
 */
/// @{

/**
 * \brief   For no reason this is not part of the member group.
 */
typedef struct {
    /**
     * \brief Some mask
     */
    uint32_t mask;
} filter_t;

/**
 * \brief  Some variable
 */
extern const uint32_t MODE_FILTER_MASK;

/**
 * \brief   Curiously this IS part of the member group.
 */
typedef bool (*for_each_cb)(const void *obj, void *opaque);

/**
 * \brief Some function
 */
uint32_t filter_id_filter_set(size_t ids_num, ...);

/// @}

Side by Side of final Doxygen output and desired Doxygen output (Photoshopped)

2. Creating a group solely consisting of data structures. -> Data structures are documented in a separate top level section and the documentation block for this group vanishes completely.

/**
 * \file doxytest2.h
 */

/**
 * \name Structures
 * \brief This documentation block will not show up 
 *        in the final file documentation. It is completely lost.
 */
/// @{

/**
 * \brief   Won't show up in group/section "Structures"
 */
typedef struct {
    /**
     * \brief Some mask
     */
    uint32_t mask;
} filterA_t;

/**
 * \brief   Won't show up as well
 */
typedef struct {
    /**
     * \brief Some mask
     */
    uint32_t mask;
} filterB_t;

/// @}

/// Some struct that should not show up in group "Structures"
typedef struct {
    int bar;
} someStruct;

Side by Side of final Doxygen output and desired Doxygen output (Photoshopped)

3. Use a module and add the data structures mit \ingroup. -> Data structure pops up in the module, but the file documentation still looks the same as above
4. Using \nosubgrouping command on file level documentation. -> No changes at all to file documentation page.

/**
 * \file doxytest.h
 * \nosubgrouping
 */

I would like that the documentation for file doxytest.h/doxytest2.h displays data structures in the group they were defined in.

The programming language is C, but I'm very limited in terms of changing the code to fit documentation needs. Doxygen version is 1.8.16. The configuration file is almost default. (I left out stuff like project name and input settings)

OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_ALL           = YES
EXTRACT_STATIC         = YES
SORT_MEMBER_DOCS       = NO
DISABLE_INDEX          = NO

Any help appreciated.

Answer 1

It took me several months to find, but the answer was deceptively simple. You just need to enable INLINE_SIMPLE_STRUCTS:

# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions
# with only public data fields or simple typedef fields will be shown inline in
# the documentation of the scope in which they are defined (i.e. file,
# namespace, or group documentation), provided this scope is documented. If set
# to NO, structs, classes, and unions are shown on a separate page (for HTML and
# Man pages) or section (for LaTeX and RTF).
# The default value is: NO.

INLINE_SIMPLE_STRUCTS  = YES

The fact that the data structures are "simple" is only a consideration of every member being publicly accessible, not the number of entries.