Как настроить Doxygen для правильного документирования категорий Objective-C

Doxygen, похоже, имеет идиосинкразическую обработку категорий Objective-C, и я хотел бы знать, смогли ли другие успешно обойти это. Я хотел бы, чтобы doxygen документировал все категории класса как отдельные объекты, независимо от того, документирован ли базовый класс или нет.

Если я добавлю разметку doxygen к категории в недокументированном базовом классе, скажем, NSString, то doxygen перечислит категорию и ее методы в списке классов как отдельный объект.

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

Результатом является задокументированная сущность NSString(Foo) в списке классов.

Но в следующем примере нет:

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

Вместо этого в последнем случае все методы CCFMyCustomClass(Foo) включены в документацию для CCFMyCustomClass — базового класса.

Следующее, хотя и часто цитируемое, похоже, не помогает решить эту проблему:


objective-c categories doxygen
person FluffulousChimp    schedule 04.01.2011    source источник

Ответы (4)


arrow_upward
3
arrow_downward

Вы можете пропустить Doxygen и использовать AppleDoc.

appledoc — это инструмент командной строки, который помогает разработчикам Objective-C создавать документацию по исходному коду в стиле Apple из специально отформатированных комментариев к исходному коду. Он предназначен для ввода как можно более удобочитаемых комментариев исходного кода и использования комментариев, а также окружающего исходного кода для создания визуально привлекательной документации в форме HTML, а также полностью проиндексированного и доступного для просмотра набора документации Xcode. Хотя существует несколько инструментов, которые могут создавать HTML-документацию для Objective-C, все известные мне средства не соответствуют минимальным целям, описанным ниже.

Он также доступен на GitHub.

person Abizern    schedule 08.01.2011
comment
Спасибо - AppleDoc выглядит гораздо более приспособленным (конечно) к парадигмам ObjC и Cocoa. Придется посмотреть на путь миграции из обширной разметки Doxygen. - person FluffulousChimp; 08.01.2011
comment
Рад, что мое небольшое предложение оказалось полезным. Удачи в миграции. - person Abizern; 08.01.2011
comment
Имейте в виду, что appledoc требует указания авторства, в отличие от doxygen. - person Feloneous Cat; 05.01.2012
comment
@FeloneousCat И это проблема, потому что…? - person Abizern; 05.01.2012
comment
AppleDoc гораздо менее гибок и не использует перечисления и файлы C++. Я бы не советовал переходить на него. - person Ilias Karim; 23.05.2013
comment
Я полностью согласен с @IliasKarim. Я использовал и Doxygen, и Appledoc, но первый намного лучше. Самое приятное в Doxygen то, что вы можете интегрировать Graphviz для создания точечных файлов. - person Evol Gate; 19.11.2014

arrow_upward
0
arrow_downward

Одно из решений, хотя и не идеальное, — это создать группу для методов категории, чтобы, по крайней мере, они были сгруппированы вместе на странице документации базового класса.

Таким образом, в соответствии со вторым примером выше:

/** @name    CCCFMyCustomClass(Foo)
             Methods defined only in CCFMyCustomClass(Foo) category */
//@{

/**
 *
 * @method someFooMethod
 * @brief  Does some foo things
 * @details First foo, then more foo, etc.
 */
- (void)someFoodMethod;

//@}

Кроме этого, я не нашел других способов разделения категорий в задокументированном базовом классе.

person FluffulousChimp    schedule 08.01.2011

arrow_upward
0
arrow_downward

Я бы хотел еще раз проголосовать за Appledoc. Гораздо проще получить хорошие результаты для Objective-C, чем для Doxygen.

person Blake Watters    schedule 14.04.2011

arrow_upward
0
arrow_downward

Я документирую свои классы (в файлах заголовков), например:

/**
 @interface MyAppDelegate
 @mainpage  The iPhone App

 This is information about my app, and appears in the main HTML page.\n\n

 As with all iOS apps, the main entry point is an App Delegate @see MyAppDelegate
 @defgroup Classes Classes
 @{
 @brief Miscellaneous Classes

 Classes that don't fit in any other category
 @{
*/
/**
 @brief The application's delegate

 A delegate object is instantiated by the main function, so this is effectively the main entry point for the app
 @see MyAppDelegate()
 */
@interface MyAppDelegate : UIResponder <UIApplicationDelegate>
...
@end

/** @} */

/** @} */

Файл .m имеет категорию расширения, в которой у меня есть мои личные методы расширения. Это выглядит так:

/**
 @category MyAppDelegate(internal)
 @addtogroup Classes
 @{
 */

/**
 @brief Application delegate class extension

 Internal extension for the application delegate
 @see MyAppDelegate
 */
@interface MyAppDelegate()
...
@end

/** @} */

@implementation MyAppDelegate
...
etc

Я получаю две html-страницы - для MyAppDelegate и MyAppDelegate(). Первая включает в себя см. также для второй, хотя см. также во второй обратно к первой не работает (похоже, есть проблема с @see category(), однако методы правильно разделены между двумя страницами.

Я думаю, что ключ в том, чтобы документировать ваши методы только внутри блоков @interface цели-C, а не внутри блоков @implementation. Я также использую блоки @defgroup и @addtogroup для группировки всех модулей определенного типа (таких как View Controllers, Models и т.д.).

Я надеюсь, что это помогает кому-то

person Derek Knight    schedule 06.05.2013