Why does swift-format think this documentation is invalid?

Using Swift
1

I'm a bit perplexed... why does swift-format give a ValidateDocumentationComments for this code:

/// foo.
///
/// - Parameter:
///   - bar: A bar.
public func foo(bar: String) {
}

The only thing it gives in the way of an error message is change the parameters of foo's documentation to match its parameters, which... I mean... it does match its parameters. Or am I missing something?

2

The plural Parameters is required when using a sublist of item(s).

-/// - Parameter:
+/// - Parameters:
 ///   - bar: A bar.

The singular Parameter can be used as follows.

-/// - Parameter:
-///   - bar: A bar.
+/// - Parameter bar: A bar.

https://github.com/apple/swift/blob/main/docs/DocumentationComments.md#parameters

3

That was actually a simplified example; the original had many parameters. I managed to figure out what it was though; it occurs if you have a parameter with a newline in its documentation, and a : character on a line other than the first one.

For example, this sets it off:

    /// Foo.
    ///
    /// - Parameters:
    ///     - bar: A bar.
    ///     - baz: A baz, in the form of a URL.
    ///         If this is a `file:` URL, funky stuff happens.
    func foo(bar: String, baz: URL) {
    }
1 Like