Best strategy for `#if` when using DocC?

DocC just drops symbols behind #if unless the documentation is built under the matching conditions. I am curious what others do to mitigate this.

I toyed with applying a static check to the project to prohibit API symbols in #if, but there are too many things that cannot be refactored to satisfy that.

3 Likes

I have the same question for GRDB

This is currently expected. To get the most accurate data possible it is recommended that you build your documentation using the same settings you plan to use on the release version of your framework/app. This is done to ensure that the API data matches what will wind up in the product accurately.

I know it is expected. The use case is generating hosted documentation for a package where symbol availability differs between macOS, Linux, Windows, etc. The question is how to best organize the code or arrange the hosted documentation to minimize confusion about the differences.

2 Likes

The way to achieve this would be to generate symbol graphs on each of those respective platforms and then feed them all to docc at compilation time. DocC supports merging symbols that appear in multiple symbol graphs it receives as input.

So something like this:

  1. Run swift package dump-symbol-graph on macOS, Linux, Windows, etc and store the symbol graphs produced on each platform in a single directory.
  2. Run docc convert <path-to-docc-catalog> --additional-symbol-graph-dir <path-to-directory-with-symbol-graphs-from-all-platforms>

DocC will produce a single documentation archive that contains the symbols for all platforms – any symbols that appear in multiple platforms will be merged into a single page. Hypothetically they should be marked with their platform availability as well but I'm not sure how well supported that is currently – certainly something we would want to fix if it doesn't work.

10 Likes