Swift 5.8 / @_documentation()

I had a great opportunity to use the (new in Swift 5.8) capability for changing the permissions level for documentation symbols, and it works beautifully. I ended up having to bound it to preserve backwards compatibility, so it makes a bit of bigger wart than you'd hope for in an annotation, but it does the trick:

#if swift(>=5.8)
@_documentation(visibility: internal)
#endif

So thank you @QuietMisdreavus !!

The only downside is now that we can hide some, I'm getting requests to hide more. In particular, some of the compiler generated conformance methods - hash(into:), !=(:), and init(from:) being the common culprits.

Are there any options to handle this scenario where I can't annotate those methods to "obscure them" from a documentation generation perspective?

/cc @hassila

3 Likes

These are what the compiler calls "synthesized symbols", and they can be hidden by passing an extra flag when getting symbol graphs: -skip-synthesized-members. This will drop all the symbols that came in from protocol extensions, which should get you most of the way there.

(Sidebar: I'm working on a new flag that will also drop symbols that are implementations of protocol requirements, to clean up docs even more: [SymbolGraphGen] add new flag to skip "protocol implementation" symbols by QuietMisdreavus · Pull Request #63726 · apple/swift · GitHub. I wanted to do a little more testing before i merge it for real, but it might be relevant to this use case.)

5 Likes

Is that exposed up through swift-docc-plugin, or would I need to step down into separately generating the symbols (using this option) in order to use this? I didn't see it as an option within swift package plugin generate-documentation --help

1 Like

I think this was work that @sofiaromorales mentioned doing at the last workgroup meeting (cf. Feat: New plugin flag for skipping synthesized symbols by sofiaromorales · Pull Request #28 · apple/swift-docc-plugin · GitHub). I don't think the plugin will let you provide arbitrary flags, but there is work on threading through this specific flag.

3 Likes

Thank you!!

1 Like

Can this flag be added directly in Xcode for workspace libraries or is it added when running a specific command? Just trying to get a better understand of how it may be used.

Did you ever find an answer for this? These excessive protocol implementation documentation artifacts make the document index unusable in my instance. There are hundreds of them listed for me and we are using DocC for a project, not just a package.

If we could plug in the -skip-synthesized-members flag somewhere, that would be ideal.

Just bumping the question here. Where do we add this -skip-synthesized-members flag?

There's an example of how to use it in the PR that @QuietMisdreavus referenced: https://github.com/apple/swift-docc-plugin/pull/28

The gist is doing something akin to:

swift package generate-documentation --skip-synthesized-symbols

Note that this will require you to use the 1.2.0 release - and as I just found while getting a link, the details are also listed in the 1.2.0 plugin release notes, which is kinda nice (thanks @ethankusters !)

1 Like