Document the protocol or the extension with concrete implementation?

In a package I have a protocol and an extension that provide concrete implementation of the protocol's functions. For example.

/// Protocol for objects that do something.
protocol Doer {
    
    /// Do something.
    static func doSomething()
}

/// Concrete implementation of the Doer protocol.
extension Doer {

    /// Do something.
    static func doSomething() {
        print("Something has been done.")
    }
}

Is it best to document the protocol, the extension or the two?

I would only document the protocol. Also, it looks like the third comment isn't used anywhere.

I just saw that Xcode only show the protocol documentation and not the extension documentation.

DocC does treat the method in the protocol and its default implementation in the extension separately, so you can document them separately. For example, this is useful if you want to document the default implementation specifically to describe what the default behavior is (depending on the context, you might want that documentation to be part of the original method in the protocol, though). Also, if you don't specify a documentation comment for the default implementation, DocC will inherit the documentation of the method in the protocol.

On the documentation page for the method in the protocol, you should see a "Default Implementations" section that contains a link to its default implementation.

1 Like