Official DocC documentation is silent on documenting closure parameters

Development Swift-DocC
,
1

I have yet to find reliable documentation for how to comment my functions which take a closure, and provide documentation on the closure parameters. Most Stack Overflow and Swift Forums posts are from 2020-2021 and encourage something like:

/// - Parameters:
///     - age: the person's current age
///     - generation: a closure that will calculate which generation this person belongs to
///     - decade: the decade in which the person was born
func doSomething(age: Int, generation: (_ decade: Int) -> String) -> String {
    // turn age into decade
    let fascinatingConclusion = generation(decade)
}

What I expect is something akin to URLSession's dataTask(with:completionHandler:) formatting: closure parameters are indented. What I get is all named parameters treated equally.

I get that Swift removed labels on closures. I'm fine if that implies that you don't want people to document them. Weird, but fine. But not documenting that you don't want people to document them is a bug.

And if DocC does want people to document closure parameters in Swift, then that should be documented. (Personally, I'd go for something like the tuple syntax combined with the type. .0 Int - the decade in which the person was born).

I mostly care that it's easy to know what is and is not possible to do based on the tool documentation. (Also enums with associated values?) This stuff is important, it seems like it should be really clear how to create proper documentation of this stuff.

In the meantime, can anyone give me pointers on how to use Xcode 15 or Xcode 16 to see properly formatted closure parameter documentation?

1 Like
2

I know you can document closure parameters on type-aliases!

3

I believe this will achieve the formatting you're looking for (though it's obviously not an ideal syntax):

/// - Parameters:
///     - age: the person's current age
///     - generation: a closure that will calculate which generation this person belongs to
///         - term `decade`: the decade in which the person was born
func doSomething(age: Int, generation: (_ decade: Int) -> String) -> String

It's taking advantage of Swift-DocC's existing term list syntax and nesting it underneath the parameter documentation.

2 Likes