如何评论苹果对Doxygen的区块扩展?

看看1.7.1和1.7.2之间的差异,我相信这一行的意思是,Doxygen扫描仪已经更新,在识别时支持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在处理它们方面不是非常出色这一事实并不是什么大问题。似乎没有任何证据表明在diff中进一步增加了对块的支持。

我不知道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