Objective-C项目Doxygen注释：存头文件还是实现文件？

一、头文件（.h）注释的定位 #

• 面向外部开发者：.h是项目对外暴露的接口契约，这里的注释会成为公开文档的核心内容，用于说明类的设计意图、公共方法的功能、参数含义、返回值规则以及使用约束，帮助使用者快速理解如何正确调用接口。
• Doxygen默认行为：Doxygen会优先解析头文件中的注释生成公开文档，这符合开源项目“接口文档优先”的原则。
• 规范重点：注释需简洁准确，避免冗余，聚焦于使用层面的信息，比如- (void)uploadFile:(NSURL *)fileURL withProgress:(void(^)(float progress))progressBlock的注释要说明fileURL的要求、progressBlock的回调时机等。

二、实现文件（.m）注释的定位 #

• 面向内部维护者：.m包含私有方法、内部逻辑实现，这里的注释用于记录实现细节，比如算法的设计思路、特殊边界的处理原因、性能优化的考量，仅供项目贡献者或维护者参考。
• Doxygen配置控制：默认情况下Doxygen不会解析.m中的私有内容注释，若需要生成内部维护文档，需在Doxyfile中设置EXTRACT_PRIVATE = YES。
• 补充价值：对于公共方法的实现，可以在.m中添加注释解释为什么这么实现，而非重复.h中的使用说明，比如某个方法选择特定排序算法的原因。

三、双端注释的影响 #

• 冗余风险：如果在.h和.m中重复编写相同的使用说明，会导致Doxygen生成的文档出现重复内容，同时增加维护成本——修改注释时需要同步更新两端，容易出现不一致。
• 互补优势：合理的双端注释是分工明确的：.h写使用指南，.m写实现细节，这种情况下，Doxygen可以分别生成面向外部的公开文档和面向内部的维护文档，两者互不冲突，反而形成完整的文档体系。
• 一致性要求：避免两端注释出现矛盾，比如.h中说明方法支持多线程调用，.m中注释却标注线程不安全，这会严重误导开发者。

四、实践建议 #

• 所有公共接口（类声明、公共属性/方法、全局常量）的使用说明必须写在.h中，确保外部开发者能获取清晰的调用指引。
• 私有方法、内部逻辑的实现细节仅在.m中添加注释，无需对外暴露。
• 开源项目通常保持EXTRACT_PRIVATE = NO，只生成公开接口文档；若需为贡献者提供内部文档，再开启该配置。
• 对于跨.m文件调用的内部方法，可在其声明处（通常是.m顶部的类别扩展）添加Doxygen注释，方便内部开发者跳转查阅。

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