title: Function header convention/expected style for methods that have blocks as parameters
body: <p>I understand that this is more a stylistic question than a technical question (and it's a minor one), but I was wondering whether or not there is a current convention for declaring documentation comments for methods that have blocks as parameters (especially if the block itself takes in parameters).</p>
  
  <p>Since I started developing in Objective-C, whenever I've faced this issue I've done the following:</p>
  
  <pre><code>/**
   * 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);
  }
  </code></pre>
  
  <p>This can certainly be applicable to any language (javascript especially), but my above example is in Objective-C because I deal with that the most.</p>