Do not skip over empty Objective C categories.

[thePsguy]

Background

For a header like below that just declares conformance for UIScreen with a protocol called GMSNavigationScreenMetrics based on properties that UIScreen already implements, Jazzy does not currently generate any documentation to indicate / declare this conformance:

/**
 * Protocol for returning information about screen metrics.
 *
 * This protocol is a subset of the screen-metric-related properties implemented by `UIScreen`.
 */
@protocol GMSNavigationScreenMetrics

/** The bounding rectangle of the screen, measured in points. */
@property(nonatomic, assign) CGRect bounds;

/** The bounding rectangle of the physical screen, measured in pixels.*/
@property(nonatomic, assign) CGRect nativeBounds;

/** The native scale factor for the physical screen. */
@property(nonatomic, assign) CGFloat nativeScale;

/** The natural scale factor associated with the screen. */
@property(nonatomic, assign) CGFloat scale;

@end

/**
 * `UIScreen` category already implements all the methods in the `GMSNavigationScreenMetrics`
 * protocol.
 */
@interface UIScreen (GMSNavigationStepImageOptions) <GMSNavigationScreenMetrics>
@end

If we explicitly add any members to this category, documentation is generated for UIScreen(GMSNavigationStepImageOptions) in the Categories section.

Change Description

This PR forces empty Objective C categories to be documented by not skipping over declarations that are empty extensions if they have are of the type objc_category.

Please let me know if you:

• Think we should do this under an optional command line flag.
• Would recommend a different / more specific check.

Thanks!

[thePsguy]

The objective c declaration in the generated docs is missing the protocol conformance.
It only includes the category: @interface UIScreen (GMSNavigationStepImageOptions)

I tried logging the doc and declaration objects for this category, and do not see any references to the protocol conformance other than in the actual doc comment.

• parsed_declaration does not match the actual header
• inherited_types is empty

Do you have any suggestions for how we could get the actual conformance to also show up correctly in the declaration in the generated docs?

for parsed_declaration: '@interface UIScreen (GMSNavigationStepImageOptions)'
---------- doc object dump ----------
{"key.always_deprecated" => false, "key.always_unavailable" => false, "key.deprecation_message" => "",
"key.doc.column" => 12, "key.doc.comment" => "`UIScreen` category already implements all the methods in the `GMSNavigationScreenMetrics`\nprotocol.",
"key.doc.file" => "/Volumes/google/src/cloud/gitpush/swift/google3/third_party/devsite/developers/en/maps/documentation/navigation/ios-sdk/reference/Jazzy/GoogleNavigation/GMSNavigationScreenMetrics.h",
"key.doc.full_as_xml" => "", "key.doc.line" => 39, "key.filepath" => "/Volumes/google/src/cloud/gitpush/swift/google3/third_party/devsite/developers/en/maps/documentation/navigation/ios-sdk/reference/Jazzy/GoogleNavigation/GMSNavigationScreenMetrics.h",
"key.kind" => "sourcekitten.source.lang.objc.decl.category", "key.name" => "UIScreen(GMSNavigationStepImageOptions)",
"key.parsed_declaration" => "@interface UIScreen (GMSNavigationStepImageOptions)", "key.parsed_scope.end" => 40,
"key.parsed_scope.start" => 39, "key.unavailable_message" => "", "key.usr" => "c:objc(cy)UIScreen@GMSNavigationStepImageOptions"}
---------- declaration object dump ----------
#<Jazzy::SourceDeclaration:0x000000011e67c810 @parent_in_code=nil, @type=#<Jazzy::SourceDeclaration::Type:0x000000011ccb8cd0 @kind="sourcekitten.source.lang.objc.decl.category",
@type={jazzy: "Category", dash: "Extension", global: true}>, @typename=nil, @objc_name="UIScreen(GMSNavigationStepImageOptions)",
@file=#<Pathname:/Volumes/google/src/cloud/gitpush/swift/google3/third_party/devsite/developers/en/maps/documentation/navigation/ios-sdk/reference/Jazzy/GoogleNavigation/GMSNavigationScreenMetrics.h>,
@usr="c:objc(cy)UIScreen@GMSNavigationStepImageOptions", @type_usr=nil, @module_name="GoogleNavigation",
@doc_module_name="GoogleNavigation", @name="UIScreen(GMSNavigationStepImageOptions)", @mark=#<Jazzy::SourceMark:0x000000011cd36400>,
@access_control_level=#<Jazzy::SourceDeclaration::AccessControlLevel:0x000000011ccb7790 @level=:internal>,
@line=39, @column=12, @start_line=39, @end_line=40, @deprecated=false, @unavailable=false,
@generic_requirements=nil, @inherited_types=[], @async=nil>

[johnfairh]

(I haven't written Objective-C in anger since the 20th century so bear with me...)

It looks like there are a couple of things going on here.

Jazzy doesn't know how to determine protocol conformances for Obj C types. This means the inherited_types thing you found is empty. The logic to deal with extensions adding protocol conformances is also Swift-specific, only firing on swift extensions rather than swift + objc.

The tougher problem is the missing angle-bracket protocol conformance thing. LibClang only generates declarations when there are doc comments; this declaration appears to omit the protocol conformance. If there is no doc comment then SourceKitten just plugs in the entire source declaration which is why you get ugly code dumps if you omit doc comments. ref.

To make progress on this would need to figure out the sourcekitten part.