时间戳

首页 > 解决方案 > Doxygen：在文件级别分组数据结构

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

问题描述

我想对数据结构使用Doxygen 分组机制。我已经将它用于功能，并且到目前为止效果很好。到目前为止，我所经历的适合有关单一类型（例如仅函数）或混合类型（例如 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 输出并排显示（Photoshop 处理）

在此处输入图像描述

  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 输出并排显示（Photoshop 处理）

在此处输入图像描述

  1. 使用模块并添加数据结构 mit \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

任何帮助表示赞赏。

标签： cdoxygen

解决方案

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

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

推荐阅读