search

swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.19k stars 127 forks source link

Support excluding symbols #406

Open juri opened 2 years ago

juri commented 2 years ago

Feature Name

Symbol exclusion

Description

Excluding symbols either via a separate exclusion list or with special documentation comment syntax (/// docc:nodoc, or something like that) would be very helpful.

Motivation

We have a framework that contains C, Objective-C and Swift. Some symbols are marked as public just for cross-language visibility reasons, and serve no purpose in the published documentation. I could move their documentation into a "PLEASE IGNORE THESE" section, but that feels a bit unprofessional.

I believe DocC does ignore symbols prefixed with an underscore, but that kind of change is really invasive in an old code base. It would be much nicer to either maintain a list of symbols to ignore or to add documentation comments that tells DocC to drop them.

For references in other tools:

Importance

Without this, switching over from Jazzy feels difficult.

Alternatives Considered

I did consider mangling the doccarchive after it has been written to disk, but it looks like it would require investigating the output format a bit more.

orchetect commented 1 year ago

Related:

juri commented 1 month ago

Seems we have support via the @_documentation attribute (linked in the previous comment) attribute for hiding Swift symbols these days, but as far as I can tell the Objective-C part is still missing.