What is the impact/effect of the `--enable-inherited-docs` with `docc convert`?

Development Swift-DocC
1

While I'm poking around in docc convert options, I'm trying to understand the effect of using --enable-inherited-docs. When I'm using it locally, I'm not able to spot any obvious differences for when it's enabled or not.

The CLI help reports:

Inherit documentation for inherited symbols

I'm afraid I wasn't clear on what it meant to be an "inherited symbol", and from where it would inherit it's documentation.

I haven't dug into the code to hunt this down yet, I was hoping there might be a fairly straightforward explanation.

2

My suspicion, based on similar terminology in Xcode's UI, is that say you have a method on a protocol declaration

protocol Foo {
  /// This is a documentation block on a protocol method requirement.
  func requiredMethod()
}

and say you have the following conformance

struct FooImpl: Foo {
  func requiredMethod() { }
}

then DocC will generate documentation on FooImpl using the documentation found on the protocol's declaration, since the conformer doesn't provide any.

I believe it also works the same for subclasses and override methods/properties

2 Likes