Как я могу правильно документировать метод с обработчиком завершения в iOS swift

Я документирую код для приложения iOS для моей компании, и теперь я перешел к методам, у которых есть обработчик завершения. Существует ли конкретный метод документирования обработчиков завершения, или я должен просто указать его как часть параметров?

например:

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

Правильно ли это или есть другой лучший способ? Или, может быть, это должно быть в части "Возврат" документации?

Спасибо

Ответ 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 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/

Ответ 2

Кажется, что в настоящее время (начиная с jan 2017) напрямую не поддерживается в синтаксисе комментариев 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

Поскольку предыдущий принятый ответ не удалось скомпилировать под 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)

Результат

Выглядит достаточно хорошо для меня!

Ответ 4

Попробуйте инструмент VVDocumenter-Xcode, который будет извлекать ваши параметры и автоматически возвращаться в документы, например, стиль javadoc.

Ответ 5

Лучший способ - создать a typealias для вашего обработчика завершения. Вы можете использовать его лучше, и ваш код станет понятным для пользователя.

С другой стороны, вы можете создать полную документацию об этом, как вы привыкли.

typealias closureType = (parameterTypes) -> (returnType)