如何评论Apple的Doxygen块扩展？

Question

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块编写文档。

Answer 1

看看1.7.1和1.7.2之间的差异，我相信这一行的含义是Doxygen扫描器在识别块类型的 typedef 时已经更新以支持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);

并获得如下输出：

对扫描程序的更改似乎添加了对block 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在处理它们时并不是非常好的事实并不是什么大问题。似乎没有任何证据表明差异中的块有任何进一步的增加支持。

Answer 2

我不了解Obj-C，但是这里有关如何标记源以生成此输出的情况，其中类型块不是接口的成员。使用@related标记以及相关接口的名称作为其目标：

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


@interface MyService : NSObject
...
@end

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