如何用 doxygen 记录 Objective-C 块？答案

【问题标题】：How to document Objective-C blocks with doxygen?如何用 doxygen 记录 Objective-C 块？
【发布时间】：2012-06-05 12:48:29
【问题描述】：

我正在开发一个基于 doxygen 文档的项目，但我不知道如何记录一个块。让我们想象一个带有块作为回调的异步函数

- (void)startWithCompletionBlock:(void (^)(BOOL success, NSError *error))block;

应该如何记录这个参数？

【问题讨论】：

How to comment Apple's block extension for Doxygen? 的可能重复项

标签： objective-c documentation doxygen objective-c-blocks

【解决方案1】：

如documentation 所示，评论一个块看起来像这样

/**
 *@brief Short description
 *
 * Extended description
 *
 *@param[in/out/in,out] success
 *@param[in/out/in,out] error
 */
(void)startWithCompletionBlock:(void (^)(BOOL success, NSError *error))block;

【讨论】：

这个答案描述了如何（正确地）为 Doxygen 创建一个评论块，而不是如何评论块参数（如问题所问）。据我所知，Doxygen 无法识别该块是什么。
语法实际上是错误的。这样，您是说您的方法有 2 个参数：success 和 error，但这是错误的，因为实际上您只有 1 个参数，即 block。
这会导致 -Wdocumentation clang 警告：“函数声明中未找到参数 'success'。您的意思是 'block'？”