Doc comment: how to document closure arguments of func argument?

young · November 11, 2020, 10:50pm

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

Jon_Shier · November 11, 2020, 11:01pm

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.

young · November 11, 2020, 11:55pm

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) {

}

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

Jon_Shier · November 11, 2020, 11:57pm

Does for me:

Xcode.

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

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

young · November 12, 2020, 12:11am

I fixed the colon and didn't change anything:

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.

glessard · November 12, 2020, 2:46am

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):

young · November 12, 2020, 3:09am

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.

young · January 7, 2021, 1:45am

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:

In Xcode Playground, Option-click do not bring up the doc comment at all, so I try with a SwiftUI view...
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:

Option-click on call site do not:

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....

seriouslyhypersonic · January 19, 2021, 5:08pm

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...

fruitcoder · September 25, 2024, 1:29pm

Are there any updates on this? For me this still isn't working in Xcode 16 and I don't even get the table shown with closure parameters in the left column and "No description." in the right one. There is just nothing. And Xcode also complains when I try to build the documentation that it can't find the Parameter.