Вот пример всех вариантов, которые я нашел с 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: 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 {}
Ноты:
- Команды должны быть в
/** 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).
@c
для отображения следующего слова в тексте пишущей машинки, как вReturns an @c NSString or @c nil.
.-[CADisplayLink addToRunLoop:forMode:]
, описание будет включать в себя именованные ссылки на другие классы (но я полагаю, что URL-адреса в Интернете также будут полезны).Swift 2.0 использует следующий синтаксис:
Обратите внимание, как
@param
сейчас- parameter
.Теперь вы также можете включить маркеры в вашу документацию:
источник
Senseful:
Иногда этого было недостаточно для меня. Закрытие Xcode и резервное копирование проекта обычно исправляют эти случаи.
Я также получаю разные результаты в файлах .h и .m. Я не могу получить новые строки, когда комментарии к документации находятся в заголовочном файле.
источник
Большая часть форматирования изменилась для Swift 2.0 (начиная с Xcode7 ß3, также верно для ß4)
вместо
:param: thing description of thing
(как это было в Swift 1.2)сейчас
- parameter thing: description of thing
Большинство ключевых слов были заменены на
- [keyword]: [description]
вместо:[keyword]: [description]
. В настоящее время список ключевых слов , которые не работают включаетabstract
,discussion
,brief
,pre
,post
,sa
,see
,availability
,class
,deprecated
,method
,property
,protocol
,related
,ref
.источник