如何在iOS swift中使用完成处理程序正确记录方法

Question

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

例如：

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

这是正确的方式还是有另一种更好的方法？或者它应该在＆＃34;返回＆＃34;部分文件？

由于

Answer 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)

结果

看起来对我来说足够好了！

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

...这样可以获得一些看起来不太糟糕的文档：

Answer 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/

Answer 4

尝试VVDocumenter-Xcode工具，它将提取您的参数并自动返回文档，如javadoc样式。

Answer 5

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

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

typealias closureType = (parameterTypes) -> (returnType)