Doxygen and Objective-C categories

Question

Although the latest releases of Doxygen claim better handling of Objective-C categories, it still seems to choke on categories in my source code. I'm wondering if someone has gotten it to document categories properly.

As an example, I have a category on NSString defined as:

@interface NSString (CCFExtensions)

with an interface file named NSString_CCFExtensions.h and implementation file NSString_CCFExtension.m

Doxygen will reference the file with the superclass; but none of the category methods are documented despite seemingly valid doxygen syntax.

Would someone who has managed to get Objective-C categories be willing to point me to the correct source markup?

Answer 1

After some regression testing (and a little common sense) the solution:

Let's say I have a category Cat1 on NSObject, for doxygen to parse my category header file, it should look roughly like this:

#import <Cocoa/Cocoa.h>

/*! \category NSObject(Cat1) 
    \abstract A category on NSObject
*/

@interface NSObject(Cat1)
    - (void)foo;
@end

and the implementation file:

#import "NSObject_Cat1.h"

@implementation NSObject(Cat1)

- (void)foo {
    //  do something
}

@end

Importantly, place no spaces between the class name and the category name.

Answer 2

@alan How do you deal with empty categories in Objective-C?

Answer 3

You can find a tutorial that covers categories here:

http://www.duckrowing.com/2010/03/18/documenting-objective-c-with-doxygen-part-i/