How can I properly document a method with a comple

问题:

I'm documenting the code for my company's iOS application, and now I've moved on to methods that have a completion handler. Is there a specific method for documenting completion handlers, or should I just put it as part of the parameters?

for example:

/**
Description
- Parameters:
     - parameter1: description
     - parameter2: description
     - completion: description
*/

Is this the right way or is there another better way? Or maybe it should be in the "Returns" part of the documentation?

Thanks

回答1:

/**
Sends an API request to 4sq for venues around a given location with an optional text search

:param: location    A CLLocation for the user's current location
:param: query       An optional search query
:param: completion  A closure which is called with venues, an array of FoursquareVenue objects

:returns: No return value
*/
func requestVenues(location: CLLocation, query: String?, completion: (venues: [FoursquareVenue]?) -> Void) { … }

taken from https://thatthinginswift.com/documentation-and-quick-help/

回答2:

Since the previous accepted answer failed to compile under Swift 3 (Function types cannot have argument label.) I would like to add an updated answer:

/**
Find User ID from Request
- Parameter from: The request containing relevant information.
- Parameter completionHandler: The callback called after retrieval.
- Parameter userId: The retrieved user id.
*/
static func extractUserId(from: RouterRequest, completionHandler: (_ userId: String) -> Void)

Result

Looks good enough for me!

回答3:

It seems like it's currently (as of jan 2017) not directly supported in the Swift comment syntax. There is an issue open, and I encourage you to vote on it/fix it :) https://bugs.swift.org/browse/SR-874

---

However, the block type could be defined separately:

/**
 - parameters:
    - error: See RequestError
    - image: Available if error is nil
*/
typealias RequestHandler = (_ error:RequestError?, _ image:UIImage?)->()

/** Requests a remote UIImage
 - parameter url: where to look for the image
 - parameter callback: invoked when request failed or completed
*/
func requstFrom(url: URL, callback:RequestHandler) { /* ... */ }

...which would allow for a somewhat not-terrible looking documentation:

回答4:

Try the VVDocumenter-Xcode tool, which will extract your parameters and return into documents automatically, like javadoc style.

回答5:

The best way is to create a a typealias for your completion handler. You can reuse it better and your code is clearer for the user.

On the other hand you can create a complete documentation about this like you used to.

typealias closureType = (parameterTypes) -> (returnType)