18

Passing the --enable-inherited-docs flag to DocC duplicates the synthesized symbol's documentation into the archive, but I don't think this should be the default behavior for at least two reasons:

  1. It makes the DocC archive size even larger, because each page now has the symbol's full documentation.
  2. Links in the synthesized symbol's documentation may not resolve when the documentation is duplicated. For example, if the documentation for a symbol synthesized from SwiftUI links to another SwiftUI API via a relative symbol link, e.g., ``View``, that symbol won't resolve when compiling documentation for your framework, because ``View`` isn't defined in your framework.

To me, the right approach here regarding how these synthesized symbols are treated is to not duplicate documentation, and instead have DocC automatically link to the original API the symbol is synthesized from. This would fit in nicely with the work @ronnqvist proposes here: Use cases for combined documentation of multiple targets in Swift-DocC. And until this is implemented, we should allow users to turn off synthesized symbols via a command-line flag to unblock them.