How to configure Doxygen to document Objective-C categories properly

Question

Doxygen appears to have idiosyncratic handling of Objective-C categories and I would like to know if others have been able to work around it successfully. I would like doxygen to document all categories on a class as separate entities, irrespective of whether the base class is documented or not.

If I add doxygen markup to a category on an undocumented base class - say NSString, then doxygen lists the category and its methods in the class list as a separate entity.

/**
 *   @category NSString(Foo)
 *   @brief A sample category on NSString
 */
 @interface NSString(Foo)
 @end

Results in a documented entity NSString(Foo) in the class list.

But, the following example does not:

/**
 *    @category CCFMyCustomClass(Foo)
 *    @brief A category on a documented base class
 */
@interface CCFMyCustomClass(Foo)
@end

Instead, in the latter case, all of the methods on CCFMyCustomClass(Foo) are included in the documentation for CCFMyCustomClass - the base class.

The following, though often cited, don't seem to help with this problem:

• Doxygen and Objective-C categories

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

Answer 1

You could skip Doxygen and go with AppleDoc.

appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set. Although there are several tools that can create HTML documentation for Objective-C, all of those know to me fall short in meeting the minimum of goals described below.

It is also available on GitHub