Objective c 具有块作为参数的方法的函数头约定/预期样式

我知道这与其说是一个技术问题，不如说是一个文体问题（这是一个次要问题），但我想知道，对于将块作为参数的方法（特别是如果块本身包含参数），是否有一个声明文档注释的现行约定

自从我开始使用Objective-C开发以来，每当我遇到这个问题时，我都会做以下工作：

/**
 * This method does some awesome stuff and takes in a completion handler when it is 
 * done. I am wondering how to format the parameters of the completion block that is
 * passed in. I currently do this as I've written below, with the parameters of the
 * callback indented in line with the description of the callback itself.
 *
 * @param completion - callback to be triggered upon success.
 *                     @param (NSArray *) - an array that holds many objects
 *                     @param (SOPost *)  - a post onto StackOverflow
 */
- (void)someMethodWithBlock:(void (^)(NSArray *, SOPost *))completion {

    /* Function does whatever it's supposed to ... for example ... */
    NSArray *arr = [NSArray new];
    SOPost *post = [SOPost new];
    completion(arr, post);
}

---

这当然可以适用于任何语言（特别是javascript），但我上面的例子是Objective-C，因为我处理的最多。

定义您的块，以便有意义地命名它。块所需的文档可以放在那里

//These blocks are pretty self explanatory but more complicated ones could warrant documentation.
typedef void(^CallbackBlock)(id object);
typedef void(^AsyncLoadingBlock)(CompletionBlock completion);
typedef NSArray*(^FilterBlock)(NSArray *objects);

- (void)someMethodWithCallback:(CallbackBlock)callback; //callback accepts a SomeClass*
- (void)loadStuffWithCallback:(CallbackBlock)callback; //callback accepts an NSArray* of SomeData*
- (NSArray *)arrayByFilteringWithBlock:(FilterBlock)filterBlock //returns a new array filtered using a FilterBlock

---

你的问题是关于如何格式化文档注释吗？是的！这是为了评论；我称之为“函数头”，但我猜它类似于“函数头描述”。具体来说，我想知道如何格式化回调的参数（@param NSArray*和@param SOPost*）。很抱歉给您带来混淆。我认为“函数头”应该替换为“文档注释”；你们能举一个打字的例子让未来的观众看到吗？是的，这对Objective-C来说似乎相当有效；你有在Javascript中使用回调并在那里记录它们的经验吗？恐怕没有，如果你需要与Javascript进行比较，请发一个新问题。不过，如果小心，“语言比较”问题很容易被标记为“过于宽泛”，并被否决。最好把你的问题局限于Javascript。