Ответ 1
Вот пример всех вариантов, которые я нашел с Xcode 5.0.2
Это было сгенерировано с этим кодом:
/** 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: [email protected]@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 {}
Заметки:
- Команды должны быть в
/** block */,/*! block *//*! block */или префикс///или//!, - Команды работают с префиксом
@(стиль headerdoc) или\(стиль doxygen). (Т.е.@bи\bоба делают одно и то же.) - Команды обычно идут перед элементом, который они описывают. (То есть, если вы пытаетесь задокументировать свойство, комментарий должен предшествовать тексту
@property.) После этого они могут появляться в той же строке с помощью/*!<,/**<,//!<,///<. - Вы можете добавить документацию к классам, функциям, свойствам и переменным.
- Все эти команды отображаются темно-зеленым текстом, чтобы показать, что они являются допустимыми командами, кроме
@returns. - Возможно, вам придется построить свой проект (или перезапустить Xcode), прежде чем появятся последние изменения в вашей документации.
Где посмотреть документацию:
1. Во время выполнения кода вы увидите краткий текст:
Это покажет краткий текст (без форматирования); если краткого текста не существует, он покажет объединение всего текста до первого @block; если ничего не существует (например, вы начинаете с @return), то он объединит весь текст, удаляя все @commands.
2. Опция-клик по имени идентификатора:
3. На панели "Инспектор быстрой помощи"
(Смотрите первый скриншот.)
4. В Doxygen
Поскольку команды в Xcode 5 совместимы с Doxygen, вы можете скачать и использовать Doxygen для генерации файлов документации.
Другие заметки
Для общего введения в Doxygen и того, как документировать код Objective-C, эта страница кажется хорошим ресурсом.
Описание некоторых из поддерживаемых команд:
-
@brief: вставит текст в начале поля описания и является единственным текстом, который появится во время завершения кода.
Следующие не работают:
-
\n: не генерирует символ новой строки. Один из способов создания новой строки - убедиться, что в этой строке нет ничего. Ни одного пробела! -
\example
Следующие элементы не поддерживаются (они даже не отображаются темно-зеленым цветом):
- \процитировать
- \docbookonly
- \enddocbookonly
- \endinternal
- \endrtfonly
- \endsecreflist
- \idlexcept
- \mscfile
- \refitem
- \relatedalso
- \rtfonly
- \secreflist
- \короткая
- \сниппет
- \оглавление
- \vhdlflow
- \~
- \"
- ,
- ::
- \|
Apple зарезервированные ключевые слова:
Apple использует зарезервированные ключевые слова, которые работают только в их документации. Хотя они выглядят темно-зелеными, похоже, что мы не можем использовать их, как Apple. Вы можете увидеть примеры использования Apple в таких файлах, как AVCaptureOutput.h.
Вот список некоторых из этих ключевых слов:
- @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref.
В лучшем случае ключевое слово вызовет новую строку в поле Description (например, @discussion). В худшем случае ключевое слово и любой текст, следующий за ним, не будут отображаться в быстрой справке (например, @class).