jazzy: Symbols in Uncompiled #if Directives List Missing Or Erroneous Declarations
Edit: As of 0.8.3
Documentation for symbols in #if
statements is no longer lost, but:
-
The declaration section for such symbols is unpredictable. Sometimes the declaration is lost completely, other times it displays the declaration of a parent symbol instead.
-
There is nothing in the output that demarcates under which compiler conditions a symbol is or is not present. (And
// MARK: -
does not work quite as well here as it does for constrained extensions (#717). See below.)
Edit: (pre‐0.8.3)
There are two aspects to the bug:
- Symbols in sections of code skipped by the compiler (
#if
) are left undocumented, with only the declaration itself appearing in the output. (Note: This does not seem to affect the coverage percentage.) - There is nothing in the output that demarcates under which compiler conditions (
#if
) a symbol is or is not present.
Original Question:
What is the intention for dealing with #if directives?
Currently Jazzy outputs declarations for sections of code skipped by the compiler, but cannot see any documentation for those symbols.
Which of the following is the goal for Jazzy:
A) It is intended to be run once for a single, unified documentation set (in which case fixes are needed to fish documentation out of uncompiled sections, and to demarcate when a symbol does and does not exist).
B) It is intended to be run separately for each operating system and build configuration (in which case fixes are needed to prevent uncompiled symbols from appearing in documentation).
Currently I can make B work by also specifying --skip-undocumented
, but I’m not sure I want to make a habit of it if Jazzy is eventually going to go the A route.
About this issue
- Original URL
- State: open
- Created 7 years ago
- Reactions: 2
- Comments: 18 (10 by maintainers)
I had to full on block it to make GitHub take it out of the reminder list. Unsubscribing alone did not work. That means no one can get my attention with @, which is unfortunate. If anyone does have something meaningful to ask, I guess you will have to send me a direct message.
🇫🇷FR: @francoisrouault, c’est exact ;
/// :nodoc:
est maintenant la seule façon. (Sauve si on peut exploiter la contrôle d’accès (internal
,private
, etc.) pour les rendre invisible.)Maintenant le but est pouvoir créer un seul site web pour (macOS/iOS/watchOS/tvOS/Linux) ⋅ (Swift 3/Swift 4) ⋅ des conditions personalisées (
#if COMPATIBLE_AVEC_APP_STORE
/#if PLUS_PETIT_FICHIER_ÉXECUTABLE
).Une fois que ça fonctionne bien, je suis d’accord que ce serait utile d’avoir une option à exclure des conditions de compilation specifiques.
🇬🇧EN: @francoisrouault, you are correct; right now
/// :nodoc:
is the only way. (Unless you can exploit ACL (internal
,private
, etc.) to make them invisible.)Right now the aim is to be able to get a single website for (macOS/iOS/watchOS/tvOS/Linux) × (Swift 3/Swift 4) × custom conditions (
#if APP_STORE_COMPATIBLE
/#if MINIMAL_EXECUTABLE_SIZE
).Once it works properly, I agree it would be useful to have a configuration option to exclude certain compile conditions.