我怎样才能在iOS中正确记录一个完成处理程序的方法swift

Question

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

例如：

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

这是正确的做法或有另一种更好的办法？或者也许它应该在文档的“返回”部分？

感谢

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

从https://thatthinginswift.com/documentation-and-quick-help/

Answer 2

尝试VVDocumenter-Xcode工具，这将提取您的参数和返回到文档自动，喜欢的javadoc样式。

Answer 3

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

另一方面，你可以创建一个完整的文档，就像你过去一样。

typealias closureType = (parameterTypes) -> (returnType)

Answer 4

采取好像它目前（以2017年1月的）不直接支持雨燕注释语法。有一个问题开了，我鼓励你就可以投票/修复:) 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 5

由于以前接受的答案未能下斯威夫特3编译（功能C型阿诺有参数标签），我想补充更新的答案：

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

结果

找我不够好！