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

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

5 голосов
/ 04 января 2011

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

Если я добавлю разметку doxygen в категорию на недокументированной базеclass - скажем 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 - базового класса.

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

Ответы [ 4 ]

3 голосов
/ 08 января 2011

Вы можете пропустить Doxygen и пойти с AppleDoc .

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

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

0 голосов
/ 06 мая 2013

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

/**
 @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 (). Однако методы правильно разделены между двумя страницами.

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

Надеюсь, это кому-нибудь поможет

0 голосов
/ 14 апреля 2011

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

0 голосов
/ 08 января 2011

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

Так что соответствует второму примеру выше: 

/** @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;

//@}

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

...