Symbols in Uncompiled #if Directives List Missing Or Erroneous Declarations

[SDGGiesbrecht]

Edit: As of 0.8.3

Documentation for symbols in #if statements is no longer lost, but:

1. 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.

2. 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 (Extension constraints including conditional conformance #717). See below.)

Edit: (pre‐0.8.3)

There are two aspects to the bug:

1. 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.)
2. 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.

[jpsim]

Ideally, you'd only ever need a single set of output documentation, which would indicate which parts are available under which conditions (e.g. platforms & versions).

[SDGGiesbrecht]

@jpsim, that’s what I suspected. I will turn this into a bug report.

I do not have time to implement it at the moment. I’m reasonably content for now with the workaround above, but I will leave the issue open because the reaction emoticons indicate that the bug is affecting others as well.

[jpsim]

By the way, generating docs with --podspec will generate them for all supported platforms and merge them together, which is what you see on http://cocoadocs.org.

[SDGGiesbrecht]

Thanks, @jpsim.

Unfortunately --podspec does not work in my case, because it would...

• not handle Linux (my current workaround does), and
• require enforcing CocoaPods support.

It also does not handle debug vs release, etc. (Though my way doesn’t either yet.)

[jpsim]

Sure, I was mostly sharing in case you wanted to study the implementation 😄

[SDGGiesbrecht]

@jpsim, Ah, I see now. Thank you.

[chitranshu]

Continuing the discussion of #869.

I did try --skip-undocumented flag on 0.8.2 and it worked as expected. All the classes under #if directives were skipped but yesterday I upgraded to Jazzy 0.8.3 and since then I am getting this issue.

Even though classes are defined under #if directive and skip-undocumented is used, I can see these classes in output doc.

I am using .jazzy.json and following is a snippet from it.

{
    "clean": true,
    "skip_undocumented": true,
    "hide_documentation_coverage": true,
    "theme": "fullwidth",
    "download_badge": false,
    "output": "../docs/swift_output/",
    "custom_categories": [
        {
             "children": [
                 "SomeClass"
              ],
              "name": "Category 1"
        },
        .
        .
        .
    ]

And following is the command line argument I am using.

jazzy --config .jazzy.json --xcodebuild-arguments -scheme,SchemeName

Following is the snippet of class which I have placed under #if directive.

#if MAGIC_MODULE
import Foundation
/// Class description
public class SomeClass: NSObject {
    
    /// Method description
    /// - Parameter callback: ....
    ///
    /// - Note: .....
    ///
    /// __Objective-C usage__
    /// ```
    /// Objective-C code here
    /// ```
    /// __Swift 3.1 usage__
    /// ```
    /// Swift code here
    /// ```
    /// - Important: ......
    public func fetch(callback: @escaping (Error?)->Void) {
        // Fetch method
    }  
}
#endif

[SDGGiesbrecht]

[Y]esterday I upgraded to Jazzy 0.8.3 and since then I am getting this issue.

I had not noticed the change, but now when I look at my own documentation, I can confirm it.

Thanks for the heads up, @chitranshu.

I have symbols that are unavailable on iOS (i.e. an #if os(macOS) statement) that have suddenly appeared in the iOS documentation, and I no longer have a way to make them disappear.

[SDGGiesbrecht]

On the other hand, it looks like the documentation for them is no longer being dropped...

Maybe now I can build a single website and describe the condition with MARK: - just like I’ve been doing with constrained extensions? I imagine it would work for methods, but types in the global scope that get their own page...? I do not know how they would look. I will probably play around with it tomorrow.

[SDGGiesbrecht]

Yes, I tried it now. It is still not perfect, but it now more or less works to run Jazzy once to document all compilation conditions (the documentation is no longer being lost). A reasonable summary of what is available when can be achieved by adding // MARK: - after each #if (which can be easily validated or scripted), or where preferred, using /// :nodoc:.

(@chitranshu, if this is not how you want to do things, you may reopen #869, but I suspect it would end up being implemented as an option, not the default. See @jpsim’s comment above.)

Notable remaining issues include:

• // MARK: - does not affect the navigation bar, nor does it appear above the main declaration of a page (the class or struct itself on its own page). Therefore, the availability of top‐level declarations must also be noted directly in their documentation comments as well.
• 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.

Eventually it would be nice if Jazzy would display the conditions automatically so // MARK: - would be unnecessary. In that respect #if and extension ... where (#717) go hand in hand.

[reitzig]

I don't think I want symbols in #if DEBUG ... #endif in customer-facing documentation.

[SDGGiesbrecht]

I don't think I want symbols in #if DEBUG ... #endif in customer-facing documentation.

@reitzig, things like #if os(macOS) and #if swift(>=4) are the real issues here. Custom compiler flags seem to be discouraged by the Swift team anyway (see here).

/// :nodoc: is always available to you when you want to hide something.

[frouo]

@reitzig @SDGGiesbrecht just to clarify, the only way to hide things in block #if DEBUG ... #endif is to use /// :nodoc: right ?
I would have expected to be hidden, especially when setting "xcodebuild-arguments": ["-configuration", "Release"] in json config file.

[SDGGiesbrecht]

🇫🇷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.

[jpsim]

🇫🇷FR: lol @SDGGiesbrecht, tu as élevé les attentes de support en traduisant tes commentaires.

🇬🇧EN: You're making the rest of us look bad.

And yes, @SDGGiesbrecht's right in our motivation for this, but it's been a source of edge case bugs like these for years.

[SDGGiesbrecht]

Closing due to a year of inactivity and a probable future of inactivity. (And because GitHub pesters me with reminders because I’m the one who opened it—if this issue still matters to you, please open your own issue instead of reopening this one. Thank you for your consideration.)

[johnfairh]

@SDGGiesbrecht would you mind just unsubscribing from the issue so we can continue to use it? Handling these multipass things is on my list though admittedly not that near the top and progress through it is pretty glacial.

[SDGGiesbrecht]

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.