如何正确记录iOS Swift中带有完成处理程序的方法？

Question

我正在为公司的iOS应用程序编写代码文档，现在我已经开始记录具有完成处理程序的方法。是否有特定的方法来记录完成处理程序，或者我应该将其作为参数的一部分进行记录？

例如：

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

这是正确的方法吗？还是有其他更好的方法？或者可能应该在文档的“返回”部分中说明？

谢谢

- DatForis

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)

结果

对我来说看起来足够好！

- Shane Hsu

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

...这将允许生成看起来不那么糟糕的文档：

- Leonard Pauli

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

- Ramy Kfoury

Answer 4

尝试使用VVDocumenter-Xcode工具，它可以自动提取您的参数并将其返回到文档中，类似于javadoc风格。

- Alfy

Answer 5

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

另一方面，您还可以像以前一样创建完整的文档。 typealias closureType = (parameterTypes) -> (returnType)

- mariusLAN