search

realm / jazzy

Soulful docs for Swift & Objective-C
https://realm.io
MIT License
7.35k stars 413 forks source link

Merge Obj-C categories into interface #457

Closed juliangrosshauser closed 8 years ago

juliangrosshauser commented 8 years ago

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 https://github.com/realm/jazzy/issues/242 and implemented in https://github.com/realm/jazzy/pull/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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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

jpsim commented 8 years ago

Done in #466.