Merge Obj-C categories into interface

[juliangrosshauser]

This is a request for mirroring Swift's behaviour of merging extensions with their extended type in Obj-C projects, only this time for categories and interfaces. This feature was requested for Swift in #242 and implemented in #343.

Say you have an interface @interface MYViewController: UIViewController @end and a category @interface MYViewController (Category) @end. The category documentation will end up in the Other Categories section, but you won't be aware of that just my looking at the interface documentation. This means you won't even notice that interface documentation is missing, unless you know that there are categories containing more documentation. This is especially an issue if your project contains lots and lots of categories and the documentation of basically one class ends up scattered in a lot of places. That's the main reason we currently can't provide jazzy documentation for PSPDFKit.

It would be a lot nicer to have the category documentation show up in the interface documentation, maybe with headers separating the categories from the interface.

[steipete]

We're going to work on this feature starting Tuesday next week - shouldn't be too hard. Any help/guides/tips appreciated. (cc @esad :) - see https://github.com/PSPDFKit-labs/jazzy

[pcantrell]

Start with merge_declarations and deduplication_key in sourcekitten.rb. It may be as simple as scanning that family of methods for swift_extension?, swift_extensible?, etc. and replacing those with more general extension?, extensible?, etc. You’ll have to think through which behaviors should remain Swift-specific (e.g. stuff related to protocol extensions).

I intentionally limited that code to Swift when I wrote that code because I wasn’t testing it on any Obj-C code, and didn’t want stupid things to happen.

[esad]

Here's my first stab at this - it feels hackish though as I rely on simple replace to match the dedup key of the class being extended, because there's no reference to the extended class in the SourceDeclaration for the category so if we want to keep it simple it would have to work like this.

@juliangrosshauser @steipete Could you try building your docs with our version and see if it has the expected behaviour? I tested on a small objc framework and seems to behave like the swift counterpart.

[esad]

@pcantrell I've had a second take on this (see #466) which is less hackish and tries to unify the swift/objc handling of extension deduplication. Let me know what you think!

[jpsim]

Done in #466.