Working around the madness of `sourceOrigin` and doccomment inheritance

Development Swift-DocC
1

right now, sourceOrigin and --skip-inherited-docs combine in ways that make it unreasonably difficult to answer the questions:

  1. what documentation should i display for symbol X?
  2. where did this documentation originally come from?

sourceOrigin provides “hints” labeling potential inheritance relationships, but makes no guarantee that these hints are valid. symbols can simultaneously have their own, specific documentation, and also inherit documentation (which may or may not exist, and independently, may or may not be available to us), and inherit documentation from symbols that have specific documentation, who in turn, inherit more general documentation.

i’ve been trying for days to formulate some rules for how to process these relationships:

  1. if symbol A has a sourceOrigin hint that points to symbol B, and symbol A’s doccomment matches symbol B’s doccomment exactly, delete symbol A’s documentation and replace it with a reference to symbol B.

  2. if symbol A has a sourceOrigin hint that points to symbol B, and symbol B has no documentation, delete the hint, and naturalize symbol A’s documentation, if it exists.

  3. if symbol A has documentation and a sourceOrigin hint that points to symbol B, and symbol B has documentation but the documentation does not match, delete the hint, and naturalize symbol A’s documentation.

  4. if symbol A has a sourceOrigin hint that points to symbol B, and symbol B has a sourceOrigin hint that points to symbol C, and symbol A’s doccomment matches symbol C’s doccomment exactly, delete symbol A’s documentation, and replace it with a reference to symbol C.

  5. if symbol A has no documentation, but it has a hint pointing to a symbol that does, symbol A should inherit the other symbol’s documentation unconditionally.

  6. if symbol B has no documentation because of --skip-inherited-docs, but it would have documentation without that option, other symbols should treat it as if --skip-inherited-docs were not used.

  7. at any time documentation that is unavailable to us may become available to us (by linking an additional symbolgraph, for example), and when this happens, symbols that inherit documentation from the newly added symbols should gain that documentation automatically.

implementation-wise, this is getting really hairy, really fast, and i’m wondering if there’s a better way to approach this.