cc @bitjammer

I actually already implemented this in c20f3db, you simply nest parameter documentation underneath the closure parameter's documentation but it's not yet consumed in Xcode, which is probably why you are seeing 'string' documentation twice. We have a radar internally documenting the need for Xcode to display it - I'll add a note there.

Here are three examples of nesting below:

{{/// Partially applies a binary operator.
///
/// - Parameter a: The left-hand side to partially apply.
/// - Parameter combine: A binary operator.
/// - Parameter lhs: The left-hand side of the operator
/// - Parameter rhs: The right-hand side of the operator
/// - Returns: A result.
/// - Throws: Nothing.

/// Partially applies a binary operator.
///
/// - Parameters:
/// - a: The left-hand side to partially apply.
/// - combine: A binary operator.
/// - Parameter lhs: The left-hand side of the operator
/// - Parameter rhs: The right-hand side of the operator
/// - Returns: A result.
/// - Throws: Nothing.

/// Partially applies a binary operator.
///
/// - Parameters:
/// - a: The left-hand side to partially apply.
/// - combine: A binary operator.
/// - Parameters:
/// - lhs: The left-hand side of the operator
/// - rhs: The right-hand side of the operator
/// - Returns: A result.
/// - Throws: Nothing.}}

I've requested a release note for when this gets fixed, so keep an eye out. I'll ping those responsible, but I'm not sure when it will be complete. Also, one thing to note is that QuickHelp may not render your documentation if you add this, because the schema for the data that the compiler sends to Xcode for QuickHelp may not match up, sorry about that. It's on my radar.

Comment by Martijn Walraven (JIRA)

Before I open a separate issue, I'm wondering if this nested syntax would also fix some other issues I'm seeing. This is while using the 'flat' parameter list format currently supported in Xcode:

• Parameters in optional closures do not seem to be documented

• Parameters for a closure type specified through a type alias do not seem to be documented

Comment by Martijn Walraven (JIRA)

To clarify, this is an example of a method I'm trying to document. I verified this isn't working in Xcode 8.3 beta 1 either. I tried both using the 'flat' parameter list format and nested parameters.

@bitjammer: Not sure if this is part of the existing issue, but it might be helpful to remind the Xcode team of the need to support optional closures and closures specified through a type alias as well.

/// Fetches a query from the server or from the local cache, depending on the current contents of the cache and the specified cache policy.
  ///
  /// - Parameters:
  ///   - query: The query to fetch.
  ///   - cachePolicy: A cache policy that specifies under what circumstances results should be fetched from the server or from the local cache.
  ///   - queue: A dispatch queue on which the result handler will be called. Defaults to the main queue.
  ///   - resultHandler: An optional closure that is called when query results are available or when an error occurs.
  ///   - result: The result of the fetched query, or `nil` if an error occurred.
  ///   - error: An error that indicates why the fetch failed, or `nil` if the fetch was succesful.
  /// - Returns: An object that can be used to cancel an in progress fetch.
  @discardableResult public func fetch<Query: GraphQLQuery>(query: Query, cachePolicy: CachePolicy = .returnCacheDataElseFetch, queue: DispatchQueue = DispatchQueue.main, resultHandler: OperationResultHandler<Query>? = nil) -> Cancellable {
    [...]
  }

public typealias OperationResultHandler<Operation: GraphQLOperation> = (_ result: GraphQLResult<Operation.Data>?, _ error: Error?) -> Void