如何为Objective-C的NS_ENUM枚举编写Doxygen文档？

苹果提供了NS_ENUM和NS_OPTION宏用于Objective-C中定义枚举，NS_ENUM的典型定义示例如下：

--- EnumName.h ---

#pragma once
#import <Foundation/NSObjCRuntime.h>

typedef NS_ENUM(NSUInteger, EnumName)
{
  EnumMemberA,
  EnumMemberB,
  EnumMemberC,
};

针对这类枚举类型及其成员，如何编写Doxygen文档才能让工具正确解析，避免解析错误或无法链接的问题？

我尝试过两种写法，但均存在问题：

1. 仅在定义前添加@brief文档块：

--- EnumName.h ---

#pragma once
#import <Foundation/NSObjCRuntime.h>

/// @file

/// @brief 简要描述。
typedef NS_ENUM(NSUInteger, EnumName)
{
  EnumMemberA,
  EnumMemberB,
  EnumMemberC,
};

结果Doxygen将该定义解析为函数，枚举在使用处（如函数/方法参数）无法被正确链接。

2. 添加@enum EnumName命令：

--- EnumName.h ---

#pragma once
#import <Foundation/NSObjCRuntime.h>

/// @file

/// @enum EnumName
/// @brief 简要描述。
typedef NS_ENUM(NSUInteger, EnumName)
{
  EnumMemberA,
  EnumMemberB,
  EnumMemberC,
};

结果Doxygen抛出警告：warning: Documentation for undefined enum 'EnumName' found，且文档块未被纳入生成输出。

使用环境：Homebrew安装的Doxygen 1.10.0，运行在Intel芯片的macOS 13.5.2系统上。

Doxygen对Objective-C的NS_ENUM宏解析需要适配其结构，以下是两种可靠的写法：

写法一：直接标注枚举类型与成员 #

无需额外的@enum命令，直接在typedef NS_ENUM上方用@brief描述枚举类型，同时为每个成员添加注释即可：

--- EnumName.h ---

#pragma once
#import <Foundation/NSObjCRuntime.h>

/// @file

/// @brief 枚举类型的用途描述，比如「用于标记操作的执行状态」
typedef NS_ENUM(NSUInteger, EnumName)
{
  /// @brief 成员A：表示操作成功完成
  EnumMemberA,
  /// @brief 成员B：表示操作执行中
  EnumMemberB,
  /// @brief 成员C：表示操作执行失败
  EnumMemberC,
};

这种写法利用Doxygen对Objective-C typedef枚举的原生识别能力，避免了宏解析带来的冲突。

写法二：@typedef+@enum组合标记（解耦文档与源码） #

如果希望文档与源码结构解耦，可以通过@typedef标记类型，再用@enum关联枚举成员，解决未定义警告的问题：

--- EnumName.h ---

#pragma once
#import <Foundation/NSObjCRuntime.h>

/// @file

/// @typedef EnumName
/// @brief 枚举类型的用途描述
/// @enum EnumName 枚举成员的集合定义
typedef NS_ENUM(NSUInteger, EnumName)
{
  /// @brief 成员A的具体说明
  EnumMemberA,
  /// @brief 成员B的具体说明
  EnumMemberB,
  /// @brief 成员C的具体说明
  EnumMemberC,
};

这种写法明确告知Doxygen，EnumName既是一个typedef类型，也是一个枚举类型，能被正确识别并生成可链接的文档。

额外配置检查 #

若仍存在解析问题，可检查Doxygen配置文件（Doxyfile）中的以下选项：

• 确保OPTIMIZE_OUTPUT_FOR_C = YES（默认开启，对Objective-C解析友好）
• 确保ENABLE_PREPROCESSING = YES（默认开启，支持宏解析）
• 开启MACRO_EXPANSION = YES，让Doxygen展开NS_ENUM宏，提升识别准确性

内容的提问来源于stack exchange，提问作者herzbube