Hide comments from SPI decls in all swiftdoc files. This applies the
same restrictions as private declarations. This is a temporary solution,
a long term fix is to emit both a public and an internal swiftdoc file.
rdar://63729195
SwiftSourceInfo files provide source location information for decls coming from
loaded modules. For most IDE use cases it either has an undesirable impact on
performance with no benefit (code completion), results in stale locations being
used instead of more up-to-date indexer locations (cursor info), or has no
observable effect (live diagnostics, which are filtered to just those with a
location in the primary file).
For non-IDE clients of SourceKit though, cursor info providing declaration
locations for symbols from other modules is useful, so add a global
configuration option (and a new request to set it) to control whether
.swiftsourceinfo files are loaded or not based on use case (they are loaded by
default).
For .swiftdoc file, we don't expose doc-comments for underscored symbols. But this
seems to be an unnecessary constraint on .swiftsourceinfo file since we put
these symbols in .swiftinterface files anyway.
Double-underscored names suggest the symbols aren't supposed to be used by framework
clients. This patch excludes the doc-comments of these symbols in swiftdoc files.
rdar://51468650
We previously shied away from this in order to not /accidentally/
depend on it, but it becomes interesting again with textual
interfaces, which can certainly be read by humans. The cross-file
order is the order of input files, which is at least controllable by
users.
Let's say I am a good citizen and document my private symbols:
/** My TOP SECRET DOCUMENTATION */
private class Foo {
}
When I go to distribute the compiled binary, I find out my private
documentation is distributed as well:
$ swiftc test.swift -emit-module -module-name "test"
$ strings test.swiftdoc
My TOP SECRET DOCUMENTATION
/** My TOP SECRET DOCUMENTATION */
If a client can't use a symbol (e.g. it's private [or internal and not
-enable-testing]) don't emit the documentation for a symbol in the
swiftdoc.
Fixes: SR-762, rdar://21453624
The test coverage implements this truth table:
| visibility | -enable-testing | documentation? |
|------------|-----------------|----------------|
| private | no | ❌ |
| internal | no | ❌ |
| public | no | ✅ |
| private | yes | ❌ |
| internal | yes | ✅ |
| public | yes | ✅ |
Modified the existing comments test coverage to expect non-public
documentation not to be emitted.
Don't rely on existing comment structure
Refuse to emit comments if the decl cannot actually have one. To
accomplish this, we move `canHaveComment` into the Decl instance. It
must also be marked `const`, since one of its existing usages operates
on a const pointer.
Perform fewer checks when serializing the standard library.
