Doxygen：在文件级别分组数据结构

Question

我想将Doxygen grouping mechanism 用于数据结构。我已经将它用于功能，并且到目前为止效果很好。到目前为止，我所经历的内容适合有关单一类型（例如仅函数）或混合类型（例如 typedef 和函数）的成员组的文档。

现在我尝试使用数据结构扩展这些成员组，但异常失败。数据结构本身始终是最重要的部分。到目前为止我的尝试：

1. 将数据结构定义放在现有的混合类型成员组中。 -> 数据结构仍记录在单独的顶级部分中。

/**
 * \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, ...);

/// @}

并排显示最终 Doxygen 输出和所需的 Doxygen 输出 (Photoshopped)

1. 创建仅由数据结构组成的组。 -> 数据结构记录在单独的顶级部分中，该组的文档块完全消失。

/**
 * \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;

并排显示最终 Doxygen 输出和所需的 Doxygen 输出 (Photoshopped)

1. 使用模块并在 \ingroup 中添加数据结构。 -> 模块中弹出数据结构，但文件文档看起来还是和上面一样
2. 在文件级文档上使用 \nosubgrouping 命令。 -> 文件文档页面完全没有变化。

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

我希望文件 doxytest.h/doxytest2.h 的文档在定义它们的组中显示数据结构。

编程语言是 C，但我在更改代码以满足文档需求方面非常有限。 Doxygen 版本是 1.8.16。配置文件几乎是默认的。 （我省略了项目名称和输入设置等内容）

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

任何帮助表示赞赏。

Answer 1

我花了几个月的时间才找到，但答案看似简单。 您只需要启用 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

数据结构“简单”的事实只是考虑到每个成员都可以公开访问，而不是条目的数量。