ObjC enum cases can have wrong doc comment

[herzi]

I have an enum type with 90%+ if the enum values being very self-explanatory, so I only documented the important ones like this:

/// This is a good type.
typedef NS_ENUM(NSInteger, MyEnum) {
    // This is completely self-explanatory and thus, won't get a doc-comment.
    MyEnumFirst,
    /// This is a very special second value.
    MyEnumSecond,
    // This one, again, is self-explanatory.
    MyEnumThird
};

This leads to the following doc-comments in generated HTML:

• MyEnum: This is a good type.
• MyEnumFirst: Undocumented.
• MyEnumSecond: This is a very special second value.
• MyEnumThird: This is a very special second value.

Now I have to add /// Undocumented. to MyEnumThird in order to obtain the expected behavior.

(Jazzy 0.7.0 installed with gem.)

[shahdhiren]

Even I have experience the same. Is there a quick fix by changing the documentation.

/// Account level
typedef NS_ENUM(NSInteger, AccountLevel) {
    /// Low
    AccountLevelLow = 0,
    /// Medium
    AccountLevelMedium,
    /// High
    AccountLevelHigh,
};

it produces wried documentation. Is there any mistake in above comments? I tried both C enums & Objective C enums but both have same results.

[johnfairh]

@shahdhiren what are you seeing wrong with jazzy's rendering of the code above? It looks OK to me I think (latest jazzy 0.8.2)?

The problem covered by this issue - undocumented enum cases get the previous doc comment - is a libclang bug/feature, best to work around it as you've done.

[shahdhiren]

Please see below Enum file that I have. It contains 3 enums where 2 enums are documented fully whereas 1 enum is partially documented.

/// Level
typedef NS_ENUM(NSInteger, Level) {
    /// Low
    Low = 0,
    /// Medium
    Medium,
    /// High
    High,
};

///Status
typedef NS_ENUM(NSInteger, Status) {
    /// INDETERMINATE
    INDETERMINATE = -1,
    /// REGISTERED
    REGISTERED = 0,
    /// VERIFIED
    VERIFIED = 1,
    /// ENROLLED
    ENROLLED = 2,
};

/// Types
typedef NS_ENUM(NSInteger, Types) {
    Type1,
    Type2,
    Type3,
    Type4,
};

Note I am testing on latest Jazzy v0.9.4 (1 Nov release)

[shahdhiren]

Also, one observation is that enums are considered as Functions in objective c and hence in documentation I can see below thing as Link instead of actual enum name:

[johnfairh]

@shahdhiren as I tried to say above, the issue whereby undocumented C enum cases get the previous doc comment is a libclang bug/feature that you need to work around.

NS_ENUM showing up as a function means that Foundation has not been imported properly by your build incantation meaning the compiler does not know that NS_ENUM is not a function.

[rodmaz]

NS_ENUM still being showed as functions, even though Foundation is imported.

@import Foundation;

[johnfairh]

If you post your code then I can take a look, but as far as I know this really does mean that foundation is not being imported properly at build time.

eg, Xcode 11.3/11.4b with test.h:

@import Foundation;

/// Types
typedef NS_ENUM(NSInteger, Types) {
    Type1,
    Type2,
};

...and jazzy --objc --umbrella-header test.h gives:

[rodmaz]

@johnfairh Not what I am seeing here.

@import Foundation;

/// AureaLogLevel
typedef NS_ENUM(NSUInteger, AureaLogLevel) {
    /**
     No logging enabled.
     */
    AureaLogLevelOff = 0,
    
    /**
     Log level *Error*.
     */
    AureaLogLevelError,
    
    /**
     Log level *Warn*.
     */
    AureaLogLevelWarn,
    
    /**
     Log level *Info*.
     */
    AureaLogLevelInfo,
    
    /**
     Log level *Debug*.
     */
    AureaLogLevelDebug,
    
    /**
     Log level *Verbose*.
     */
    AureaLogLevelVerbose
};

I am getting however the following warnings, which may ring a bell:

using sysroot for 'MacOSX' but targeting 'iPhone' [-Wincompatible-sysroot]

xxxxx/Headers/AureaManager.h:23:9: fatal error: module 'UIKit' not found

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: constant NSString, constant NSString, constant NSString, constant NSString, constant NSString, constant NSString

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: function NS_ENUM, function NS_ENUM, function NS_ENUM, function NS_ENUM

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: unexposed , unexposed , unexposed , unexposed 

[johnfairh]

Ok good, so those first two are compiler errors (from clang) resulting in foundation not being pulled in, causing the enum problem & the last three errors (from jazzy). You'll need to work through fixing the compiler errors. I'm not an objc developer but I guess you're missing --sdk iphonesimulator or something, just by reading what it says?

[rodmaz]

SDK (--sdk iphoneos) was indeed missing. Thanks. However the problems continue:

Headers/AureaManager.h:23:9: fatal error: could not build module 'UIKit'

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: constant NSString, constant NSString, constant NSString, constant NSString, constant NSString, constant NSString

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: function NS_ENUM, function NS_ENUM, function NS_ENUM, function NS_ENUM

Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: unexposed , unexposed , unexposed , unexposed 

This is really messy as those examples in README.md also show some cryptic configuration w/o any explanation what these parameters mean (eg. AFNetworking does such...) and some do not even seem to work.

I just tried to add this parameter below:

--xcodebuild-arguments '-project,AureaFramework.xcodeproj,-scheme,AureaFramework' 

And now I got an error:

Showing Recent Messages
Unrecognized arguments: -project, -schem

/Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/lib/jazzy/executable.rb:36:in `execute_command': /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/bin/sourcekitten ["doc", "-project", "AureaFramework.xcodeproj", "-scheme", "AureaFramework"] (RuntimeError)



Unrecognized arguments: -project, -schem

	from /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/lib/jazzy/sourcekitten.rb:266:in `run_sourcekitten'

	from /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/lib/jazzy/doc_builder.rb:78:in `block in build'

	from /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/lib/jazzy/doc_builder.rb:76:in `chdir'

	from /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/lib/jazzy/doc_builder.rb:76:in `build'

	from /Library/Ruby/Gems/2.6.0/gems/jazzy-0.13.1/bin/jazzy:15:in `<top (required)>'

	from /usr/local/bin/jazzy:23:in `load'

	from /usr/local/bin/jazzy:23:in `<main>'

[johnfairh]

Try --sdk iphonesimulator (if I do --sdk iphoneos I get your problem!)

The objc side uses libclang, not xcodebuild, so trying to pass stuff like -scheme won't work.

[rodmaz]

Bingo! Now it works fine. Thanks a lot!