如何为Doxygen的Apple块扩展添加注释？

Question

Doxygen宣布在1.7.2版本中支持Apple的block扩展。我想知道生成文档的语法是什么，但是我没有找到任何提示 - 即使在doxygen配置文件（版本1.7.2）中也没有。
更新：于2011年8月14日发布了1.7.5版本。但我仍没有找到如何编写Apple blocks文档的方法。

- JJD

Answer 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);

并获得如下输出：

他们的扫描仪的更改似乎增加了对块typedef的支持，如下所示：

///
/// 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在处理它们方面表现得不太好并不是什么大问题。在差异中似乎没有任何进一步添加块支持的证据。

- ipmcc

Answer 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

- dougkramer