【问题标题】：How can I properly document a method with a completion handler in iOS swift如何在 iOS swift 中使用完成处理程序正确记录方法
【发布时间】：2016-01-22 07:25:59
【问题描述】：

我正在为我公司的 iOS 应用程序记录代码，现在我已经转向具有完成处理程序的方法。是否有记录完成处理程序的特定方法，还是应该将其作为参数的一部分？

例如：

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

这是正确的方法还是有其他更好的方法？或者它应该在文档的“退货”部分？

谢谢

【问题讨论】：

标签： ios swift documentation

【解决方案1】：

由于之前接受的答案在 Swift 3 下编译失败（函数类型不能有参数标签。）我想添加一个更新的答案：

/**
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)

结果

对我来说已经足够好了！

【讨论】：

【解决方案2】：

目前（截至 2017 年 1 月）似乎在 Swift 注释语法中不直接支持。有一个问题悬而未决，我鼓励您投票/修复它:) https://bugs.swift.org/browse/SR-874

但是，块类型可以单独定义：

/**
 - 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) { /* ... */ }

...这将允许看起来有点不可怕的文档：

【讨论】：

【解决方案3】：

/**
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) { … }

取自https://thatthinginswift.com/documentation-and-quick-help/

【讨论】：

【解决方案4】：

试试VVDocumenter-Xcode 工具，它会自动提取参数并返回到文档中，就像javadoc 风格一样。

【讨论】：

【解决方案5】：

最好的方法是为您的完成处理程序创建一个typealias。您可以更好地重用它，并且您的代码对用户来说更清晰。

另一方面，您可以像以前一样创建一个完整的文档。

typealias closureType = (parameterTypes) -> (returnType)

【讨论】：