1 
/// Some description Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
/// ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
/// ut aliquip ex ea commodo consequat.
///
/// - Parameter areInIncreasingOrder: some closure that takes two arguments, but how to document the arguments?
func foo<Element>(by areInIncreasingOrder: (Element, Element) -> Bool) {

}

foo(by: { (a: Int, b: Int) in true })

It's showing "No description" now. How to add documentation of these?

Screen Shot 2020-11-11 at 2.05.43 PM
Screen Shot 2020-11-11 at 2.05.43 PM1030×732 154 KB

2 Likes
2

You can make it part of the parameter list:

/// Do thing.
///
/// - Parameters:
///   - closure: Closure
///   - one: One
///   - two: Two
func doThing(_ closure: (_ one: String, _ two: String) -> Void) {}

Rendering is still rather broken though.

4

Doesn't work:

/// Some description Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
/// ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
/// ut aliquip ex ea commodo consequat.
///
/// - Parameters
///     - areInIncreasingOrder: some closure that takes two arguments, but how to document the arguments?
///     - a: aaa where are you?
///     - b: bbb hello hello!!!
func foo<Element>(by areInIncreasingOrder: (_ a: Element, _ b: Element) -> Bool) {

}

Screen Shot 2020-11-11 at 3.50.36 PM
Screen Shot 2020-11-11 at 3.50.36 PM1052×930 192 KB

It's seeing the name a and b, but it showing two separate "Parameters" block and the second one show "No description."

5

Does for me:

Screen Shot 2020-11-11 at 6.56.48 PM
Screen Shot 2020-11-11 at 6.56.48 PM1552×860 158 KB

Xcode. :man_shrugging:

Perhaps it's broken because you're missing the : after Parameters?

(I wish Xcode could validate and format doc comments.)

2 Likes
6

I fixed the colon and didn't change anything:

Screen Shot 2020-11-11 at 4.07.54 PM
Screen Shot 2020-11-11 at 4.07.54 PM2054×1104 396 KB

I'm on Xcode 12.2 beta 4, are you on this one?

So I Option-Cmd-/ on this and Xcode generated this comment, it doesn't see the closure arguments:

/// <#Description#>
/// - Parameter areInIncreasingOrder: <#areInIncreasingOrder description#>
func bar(by areInIncreasingOrder: (_ a: String, _ b: String) -> Bool) {

}

So your formatting is correct. It's just not working for me for some reason.

1 Like
7

What you're showing has the parameters in the "Discussion" section, so they haven't been parsed correctly. The following works for me on Xcode 12.2b4:

/// Description
/// - Parameter closure: closure description
/// - Parameter first: first parameter
/// - Parameter second: second parameter

func foo<Element>(by closure: (_ first: Element, _ second: Element) -> Bool) {}

Then I get (in a playground, if that matters):

Screen Shot 2020-11-11 at 19.41.25
Screen Shot 2020-11-11 at 19.41.251020×662 114 KB

1 Like
8

Thanks for confirming! I found the problem: on the second level after - Parameters, I had one space prefix, it wants (exactly?) two spaces:

/// Some description.
///
/// - Parameters:
///   - areInIncreasingOrder: some closure that takes two arguments, but how to document the arguments?
///   - a: aaa where are you?
///   - b: bbb hello hello!!!
func foo<Element>(by areInIncreasingOrder: (_ a: Element, _ b: Element) -> Bool) {

}

Still, option-cmd-/ generate doc comment doesn't include the closure parameter. This is likely a bug.

:pray:

9

Edit: Maybe a bug? [SR-14026] Doc comment for closure parameters of function parameter: work for top level func, but not nested member func · Issue #60696 · apple/swift · GitHub

In Xcode Version 12.3 (12C33), doc comment of closure parameters seems to be broken for nested func:

  1. In Xcode Playground, Option-click do not bring up the doc comment at all, so I try with a SwiftUI view...
  2. doc comment of closure parameters work only for top level func, the exact same doc comment is "No description" for nested func inside extension:

Option-click on definition works:

Screen Shot 2021-01-07 at 19.11.23
Screen Shot 2021-01-07 at 19.11.23871×373 56.9 KB

Option-click on call site do not:

Screen Shot 2021-01-07 at 19.11.45
Screen Shot 2021-01-07 at 19.11.451158×688 82.4 KB 

import SwiftUI


/// Description
/// - Parameter closure: closure description
/// - Parameter first: first parameter
/// - Parameter second: second parameter
func docfoo<Element>(by closure: (_ first: Element, _ second: Element) -> Bool) {}

/// Description
/// - Parameters:
///   - closure: closure description
///   - first: first parameter
///   - second: second parameter
func moredocfoo<Element>(by closure: (_ first: Element, _ second: Element) -> Bool) {}

extension Array {
    /// Description
    /// - Parameter closure: closure description
    /// - Parameter first: first parameter
    /// - Parameter second: second parameter
    func docfoo<Element>(by closure: (_ first: Element, _ second: Element) -> Bool) {}
}

struct ContentView: View {

    func junk() {
        // works here
        docfoo(by: { (a: Int, b: Int) in a < b })
        // works here
        moredocfoo(by: { (a: Int, b: Int) in a < b })
        let a = [Int]()
        // do not work here (No description)
        a.docfoo(by: { (a: Int, b: Int) in a < b })
    }


    var body: some View {
        Text("Hello")
    }
}

Can someone kindly verify for me please. I thought it was my mistake in formatting....
:pray:

10

I have the exact same issue. Option click on definition site works, but on call site it's broken. The member function I am documenting is not generic, but the struct is. I don't know if that is related, however...