`@_exported import`s should not emit symbols from external dependencies

[stephencelis]

Description

Sometimes, a library will re-export the interface of an external dependency, especially if it relies on a hyper-modularized toolchain of dependencies.

While not quite "hyper," the Composable Architecture has 4 external dependencies that it re-exports:

https://github.com/pointfreeco/swift-composable-architecture/blob/main/Sources/ComposableArchitecture/Internal/Exports.swift#L1-L4

These dependencies are useful on their own, and they are documented on their own, but they also are required by the core library often enough that we feel it is unfair to push this burden of imports onto library users.

Duplicating their interfaces and documentation across multiple modules is confusing and wasteful in this instance, and creates a lot of work for us to hide all these symbols somehow.

I can see an argument for aggregating the documentation of internal modules that are re-exported (e.g., in Vapor), but external modules should probably be on the chopping block.

Checklist

• [ ] If possible, I've reproduced the issue using the main branch of this package.
• [X] This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

I expect symbols from external dependencies that are @_exported imports to be omitted from my package's documentation.

Actual behavior

All symbols are present.

Steps To Reproduce

1. Clone https://github.com/pointfreeco/swift-composable-architecture
2. Check out a stable commit (d98e555d0e6559f1a0dc7d70603800cd33af7a03)
3. Open in Xcode 14 beta 3
4. Build documentation
5. See that symbols from Case Paths and other external libraries are emitted

Swift-DocC Version Information

Xcode 14 beta 3

Swift Compiler Version Information

swift-driver version: 1.60 Apple Swift version 5.7 (swiftlang-5.7.0.120.1 clang-1400.0.28.1)
Target: arm64-apple-macosx12.0

[franklinsch]

Thanks for filing @stephencelis. There was some discussion about this in forums and we can continue the conversation there.

[groue]

Hello, I meet the same problem, which is that when module A exports module B, DocC includes all symbols of module B in the documentation for module A.

I find this really annoying, given:

• The documentation of the module B is already available on its own.
• The documentation of symbols specific to the module A are very difficult to find in the merged documentation.

In the context of a private local package developed for an application that exports a public library package, this merging has even less meaning. The local package is obviously not the home for the library symbols! In the end, efforts of documenting the local package are hindered by the impossibility to get a focused doc :-/ This is really contrarian to the goals of DocC.

Looking at the Composable Architecture mentioned in the OP, I can see that:

• The documentation hosted on SPI does not show exported symbols: https://pointfreeco.github.io/swift-composable-architecture/1.2.0/documentation/composablearchitecture
• When I download the TCA sources and build the doc with Xcode, exported symbols are visible (this issue).

I could not spot the cause of this difference. No special @ directive in the DocC files. No specific configuration in .spi.yml.

But my main concern in the Xcode documentation window. Has anyone a clue for hiding exported symbols in the Xcode documentation window?