Комментарии для документирования кода Objective-C

В настройках Xcode есть такие интересные вещи как Documentation Markup и Documentation Markup Keywords.
Из этого следует, что Xcode поддерживает комментарии для описания кода.

Я советую для Documentation Markup Keywords выбрать более темный оттенок чтобы можно было различать ключевые слова в комментариях документирующих код.

Документировать можно классы, функции, свойства и переменные.

Есть два способа: однострочный комментарий и блочный комментарий.

// Normal inline comment
/// Documentation comment

/* Normal block
comment */
/** Documentation block
comment */

Пример описания функции:

/// @description Вывести оценку.
- (void)printGrade;

Autocomplete-подсказка будет выглядеть так:

А инспектор помощи будет отображать следующую информацию:

Для того чтобы Xcode отображал контекстную помощь может понадобиться сделать сборку проекта, а в некоторых случаях возможно нужно перезапустить IDE. В редких случая нужно почистить DerivedData:
rm -rf ~/Library/Developer/Xcode/DerivedData/*

Блочные комментарии работают аналогичным образом:

/**
 @description Передвигает автомобиль.
 @available Версия 1.0 до 2.2
 */
- (void)moveAtLocation:(CGPoint)aLocation;



Ключевые слова начинающиеся с префикса @ также называются HeaderDoc-тегами. Эти ключевые слова являются командами. Есть два стиля:
  • headerdoc стиль использует символ @, например, @b;
  • doxygen стиль использует символ \, например, \b.
Команды обычно предшествуют тому, что они описывают. Например, если вы документируете свойство, то команду надо размещать перед объявлением @property. Но можно разместить и после, но на той же строчке, для этого надо использовать комментарии: /*!<, /**<, //!<, ///<.

Есть ряд инструментов для создания документации из исходного кода. 

Все они нацелены на распознавание специальных комментариев и ключевых слов (@param, @return, @throws).

Xcode поддерживает комментарии в стиле Doxygen:

Doxygen позволяет использовать //! для однострочных комментариев, и /*! block */ для блочных комментариев. Пример:

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;

Inline help
Quick help. Чтобы открыть такую подсказку надо нажать ⌥ Option + клик на методе.
Sidebar help

Чтобы не париться каждый раз с написанием комментариев к функциям, можно сделать сниппет следующего содержания:

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

Для этого надо просто написать в редакторе вышеприведенный код, выделить его и перетащить на панель сниппетов.


Doxygen поддерживает большое количество команд. Но по всей вероятности не все они поддерживаются в Xcode. То что поддерживается можно посмотреть в официальной документации.

Пример обширного документирования метода:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

Соответствующая контекстная помощь будет выглядеть так:


Не все команды из Doxygen работают. Например, перевод на новую строку \n не работает. Команда \example для приведения примера тоже не работает. Также не поддерживаются следующие команды:
  • \cite
  • \docbookonly
  • \enddocbookonly
  • \endinternal
  • \endrtfonly
  • \endsecreflist
  • \idlexcept
  • \mscfile
  • \refitem
  • \relatedalso
  • \rtfonly
  • \secreflist
  • \short
  • \snippet
  • \tableofcontents
  • \vhdlflow
  • \~
  • \"
  • .
  • ::
  • \|

Apple использует в своей документации (например, AVCaptureOutput.h) некоторые зарезервированные ключевые слова: @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref. Но похоже, что мы не можем их использовать также как это делает Apple.


исходники

--

Теги: , ,