Filtering out @_exported import symbols from symbol graphs

is there a way to exclude @_exported symbols from symbol graphs?

APIs exposed via @_exported import are included in the module's symbol graph because they're part of the module's API. You can't opt-out of this behavior right now. Can you elaborate on why you would want to omit symbols that come from @_exported import?

i need to know which module (and eventually, which package) symbols really belong to. if symbols from ReexportedModule show up in ImportingModule, they will be duplicated between the documentation for ReexportedModule and ImportingModule.

aside from the duplication, they also have identical USRs, which causes a whole host of problems related to ID collisions. if we solve this problem by uniquing based on symbol ID, then this opens up the possibility that symbols could be “kidnapped” from their original namespace and moved to a package+module scope they are not originally from.

An issue was opened in Swift-DocC to track this as well: `@_exported import`s should not emit symbols from external dependencies · Issue #331 · apple/swift-docc · GitHub.

In the kind of setup the mentioned project has, where a module A export-imports a module B and documentation B is being published independently, it would make sense for DocC to recognize that and instead of re-emitting B's symbols in A's documentation, to instead have A link to B in some way. This is something that should happen automatically when building documentation for multiple targets at once (e.g., via Allow combined documentation of multiple targets · Issue #255 · apple/swift-docc · GitHub).

In cases where you're not building A and B together (e.g., B is dynamically linked), and thus the build system doesn't know whether you'll be publishing documentation for B, it would still be good to provide extra flexibility to exclude B's symbols. @QuietMisdreavus has been toying with the idea of a @_hidden attribute that you'd attach to @_exported imports to indicate that the symbols should be excluded from the build.

2 Likes