修复明确的 link 警告

Question

我有一个相当大的 doxygen 项目，有些文件标记为 @internal，有些则没有。当我构建内部文档时没有生成警告，但是当我尝试构建非内部文档时我收到了一些警告：

some_header.h:61 警告：无法解析对 'MyStruct' 的显式 link 请求 some_header.h:58 警告：无法解决对 'AnotherMyStruct' 的显式 link 请求 some_header.h:58 警告：无法解决对 'AnotherMyStruct' 的显式 link 请求 some_header.h:61 警告：无法解析对 'MyStruct' 的显式 link 请求

但是some_header.h是内部的。作为一个想法，我认为它包含在非内部文件中，但这是错误的。我删除了 header 的所有内容，但消息并没有消失。我该如何解决这个警告？ P.S。警告重复意味着有2处错误？

$doxygen -x
FULL_PATH_NAMES        = NO
JAVADOC_AUTOBRIEF      = YES
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_STATIC         = YES
QUIET                  = YES
WARN_IF_UNDOCUMENTED   = NO
WARN_FORMAT            =
FILE_PATTERNS          = *.c *.h
RECURSIVE              = YES
EXAMPLE_PATTERNS       =
SOURCE_BROWSER         = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
ALPHABETICAL_INDEX     = NO
HTML_OUTPUT            =
SEARCHENGINE           = NO
GENERATE_LATEX         = NO
LATEX_OUTPUT           =
PDF_HYPERLINKS         = NO
USE_PDFLATEX           = NO
RTF_OUTPUT             =
MAN_LINKS              = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = (a lot of)
TEMPLATE_RELATIONS     = YES

重现问题的简单示例： flags.h:

/**
 * @file
 * @brief Public Flags.
 */
#ifndef PUBLIC_FLAGS_H
#define PUBLIC_FLAGS_H
#pragma once
    
/**
 * Public flags
 */
typedef enum {
    FLAG_READ           = 1,    /**< reading allowed         */
    FLAG_WRITE          = 2,   /**< writing allowed         */
} PublicFlags;

#endif /* PUBLIC_FLAGS_H */

info.h

/**
 * @file
 * @brief Public header.
*/
#ifndef TEST_PUBLIC_H
#define TEST_PUBLIC_H
#pragma once

#include "flags.h"

/**
 * Defines public enum.
 */
typedef enum EPublicEnum {
    TestEnum1,    /**< enum 1 */
    TestEnum2,    /**< enum 2 */
    TestEnum3     /**< enum 3 */
} PublicEnum;

/**
 * Defines public struct.
 */
typedef struct SPublicStruct {
    PublicEnum     state;    /**< state (see #PublicEnum). */
    unsigned      flags;     /**< set of flags see #PublicFlags.*/
} PublicStruct;

#endif /* TEST_PUBLIC_H */

internal_enums.h

/**
 * @internal
 * @file
 * @brief  Internal Enums
 */
#ifndef INTERNAL_ENUMS_H
#define INTERNAL_ENUMS_H
#pragma once

#include "flags.h"
#include "info.h"

/**
 * Possible types:
 *
 *  TypeMisc - Misc type.
 *  TypeIo   - IO type.
 */
typedef enum {
    TypeMisc,
    TypeIo,
} InternalEnumType;

/** Owner type. */
typedef enum {
    Kernel  = 0,    /**< kernel. */
    User    = 1     /**< user. */
} InternalEnumOwner;

#endif /* INTERNAL_ENUMS_H */

internal_struct.h

/**
 * @internal
 * @file
 * @brief  Internal structures.
 */
#ifndef INTERNAL_STRUCT_H
#define INTERNAL_STRUCT_H

#include "internal_enums.h"

typedef struct SInternalStruct {
    rtl_uint8_t   owner : 1;        /**< values from #InternalEnumOwner */
    rtl_uint8_t   type : 1;         /**< values from #InternalEnumType */
} InternalStruct;

#endif /* INTERNAL_STRUCT_H */

问题：警告：无法解析对 'InternalEnumOwner' 的显式 link 请求

警告：无法解决对 'InternalEnumType' 的显式 link 请求

Answer 1

关于 \internal 命令在 doxygen 中的作用存在误解，来自文档：

24.29 \internal

This command starts a documentation fragment that is meant for internal use only. The fragment naturally ends at the end of the comment block. You can also force the internal section to end earlier by using the \endinternal command. If the \internal command is put inside a section (see for example \section) all subsections after the command are considered to be internal as well. Only a new section at the same level will end the fragment that is considered internal. You can use INTERNAL_DOCS in the configuration file to show (YES) or hide (NO) the internal documentation.

这意味着 \internal 和 \endinternal 之间的注释（或注释块的结尾）不是文档的一部分（除非设置 INTERNAL_DOCS 已设置），在这种情况下，它只是关于以下部分：

/**
 * @internal
 * @file
 * @brief  Internal structures.
 */

所以这里的\internal命令没有达到预期的效果，应该删除。

实际需要的（当我理解正确时）是不使用整个文件。这可以通过以下任一方式完成：

添加设置EXCLUDE_PATTERNS = internal*

或

明确列出应该使用的所有文件和目录，这是通过添加设置 INPUT = info.h flags.h

如果只有文件的一部分，即文档和代码，不应该进入文档，可以使用命令 \cond ... \endcond。要仅禁用文档块的一部分，命令 \if .. \endif 很有用。两组命令都与设置一起使用 ENABLED_SECTIONS.

有关上述命令的说明，请参阅 doxygen 手册（例如 https://www.doxygen.nl/manual/index.html and more specifically the chapters: https://www.doxygen.nl/manual/config.html and https://www.doxygen.nl/manual/commands.html）

修复明确的 link 警告

Fix explicit link warning

doxygen