如何评论 Apple 对 Doxygen 的块扩展？答案

【问题标题】：How to comment Apple's block extension for Doxygen?如何评论 Apple 对 Doxygen 的块扩展？
【发布时间】：2010-10-12 15:06:35
【问题描述】：

Doxygen announced in their changelog for version 1.7.2 to support Apple's block extension。我想知道生成文档的语法是什么。我找不到任何提示 - 在 doxygen 配置文件（1.7.2 版）中也没有。
更新： 1.7.5 版于 2011 年 8 月 14 日发布。我仍然没有找到了解如何为 Apple 块编写文档。

【问题讨论】：

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

【解决方案1】：

看看 1.7.1 和 1.7.2 之间的差异，我相信这行的意思是 Doxygen 扫描器已经更新以在识别块类型的 typedefs 时支持 Apple 的块语法.例如，您可以像这样记录函数指针 typedef：

///
/// This is a typedef for a function pointer type. 
/// It takes an NSUInteger parameter, an id adopting protocol Foo, and has no return value.
/// 
typedef void (*MyFunctionPtrType)(NSUInteger p1, id<Foo> p2);

并得到这样的输出：

对扫描仪的更改似乎增加了对块类型定义的支持，如下所示：

///
/// This is a typedef for a block type. 
/// It takes an NSUInteger parameter, an id adopting protocol Foo, and has no return value.
/// 
typedef void (^MyBlockType)(NSUInteger p1, id<Foo> p2);

事实上，使用最新版本的 Doxygen，会产生如下输出：

您可以记录块类型的全局变量，但行为有点不稳定。例如，这样：

///
/// This is a global variable of type MyBlockType. It logs the parameters to the console.
///
MyBlockType myGlobalBlock = ^(NSUInteger p1, id<Foo> p2){

    /**
     * This is a block comment inside my block, which would get 
     * concatted into the "in body" description if this were a function.
     * but won't be because this is a block.
     */
    NSLog(@"p1: %lu p2: %@", p1, p2);
};

///
/// This is the definition for the function MyFunction
/// 
void MyFunction(NSUInteger p1, id<Foo> p2)
{
    /**
     * This is a block comment inside my function, which will get 
     * concatted into the "in body" description.
     */

    NSLog(@"p1: %lu p2: %@", p1, p2);
}

我得到了这个输出，这有点不像我想要的：

幸运的是，我怀疑块类型的全局变量在实践中并不是一种常见的模式，因此 Doxygen 在处理它们方面并不是特别出色这一事实并不是什么大问题。似乎没有任何证据表明对 diff 中的块有任何进一步的支持。

【讨论】：

【解决方案2】：

我不知道 Obj-C，但这里是如何标记源以在类型块不是接口成员的情况下生成此输出。使用@related标签，以相关接口的名称为目标：

/**
 * @related MyService
 *
 * The completion handler invoked when `unsubscribe` returns.
 */
typedef void(^MyServiceUnsubscribeCompletion)(NSError *error);


@interface MyService : NSObject
...
@end

Dimitri 自己提供了解决方案： https://bugzilla.gnome.org/show_bug.cgi?id=720046

【讨论】：