I'm migrating to DocC for a project and I'm finding that some files, which have API docs in them, are missing their docs in the DocC generated docs.
It's happening to some of my protocols and enums (while many others are fine). The project is largely ObjC (with some Swift creeping in thankfully) and the problem types are ObjC, though others that work fine are also ObjC.
There's nothing I can spot in the types or docs that differs between the ones that work and the ones that don't.
Interestingly the pages for the types that have the missing docs also don't have the language switcher at the top right, but the pages which have all their docs shown do have that switcher
I tried looking at the output in Xcode when building the docs, as well as from xcodebuild docbuild but can't see anything referencing problems with the files or types in question. Is there a way to enable more doc issue logging or hone in on what might be going wrong?
Is the granularity of the issue at the file level? If so make sure that the headers for which the pages are missing are "public" and belong to the correct target.
DocC is currently broken for some common cases, e.g. it won't generate documentation pages for protocol extensions on types from other modules. Is that what you're seeing?
@daniel-grumberg Not 100% sure what you mean by the granularity being at the file level, I guess you mean does everything in the file have its docs missing? In which case one of the enums that's missing its docs is also in a file with a delegate that's missing its docs (though I tried splitting the enum out into a different header and that didn't help and another enum that's not showing up its docs is on its own in a header).
Extra info: this is for a framework, if that makes any difference
The headers in question are all public, part of the framework and included in the framework header
And just to be clear the protocols and enums show up in the documentation, they're not just showing their docs and the experimental docs coverage claims their undocumented.
The docs also show up perfectly in Xcode's quick help, so it seems related to building the DocC archive.
To give an example, the following shows up the docs without its comments:
#import <Foundation/Foundation.h>
#ifndef ADOCLESSDELEGATE_PROTOCOL
#define ADOCLESSDELEGATE_PROTOCOL
NS_ASSUME_NONNULL_BEGIN
/// Protocol to inform about the result of the something/else operation
@protocol ADocLessDelegate <NSObject>
/// Notifies the conforming object that the thing successful and return the data that was received
/// - Parameters:
/// - data: Payload
- (void)thingDidSucceed:(NSData*)data;
/// Notifies the conforming object that the thing failed with a specific error.
/// - Parameters:
/// - error: Error that caused the failure.
- (void)thingDidFailWithError:(NSError* _Nonnull)error;
/// Notifies the conforming object that the other thing successful and return the data that was received
/// - Parameters:
/// - data: Payload
- (void)otherThingDidSucceed:(NSData*)data;
/// Notifies the conforming object that the other thing failed with a specific error.
/// - Parameters:
/// - error: Error that caused the failure.
- (void)otherThingDidFailWithError:(NSError* _Nonnull)error;
@end
NS_ASSUME_NONNULL_END
#endif
And the following works fine
#import <Foundation/Foundation.h>
NS_ASSUME_NONNULL_BEGIN
#ifndef ADOCUMENTEDDELEGATE_PROTOCOL
#define ADOCUMENTEDDELEGATE_PROTOCOL
/// The conforming object will be notified of events
@protocol ADocumentedDelegate<AnotherDelegate>
/// Notifies the conforming object that the thing failed with an error.
/// - Parameters:
/// - error: Error object containing information about the failure's cause.
///
- (void)theThingDidFailWithError:(NSError*)error NS_SWIFT_NAME(theThingDidFail(with:));
#endif
NS_ASSUME_NONNULL_END
@wadetregaskis Not sure.. the enums don't fit into that category it seems (though maybe there are different problems with that). The problem protocols all inherit from <NSObject> but others that do that show their full docs fine (though maybe the bug manifests part way through the parsing?)
OK I understand what you mean, so the pages are picked up correctly but the documentation prose is missing. Would you be able to file and feedback (Bug Reporting - Apple Developer) and attach the DerivedData folder of your project after the documentation build?
