Ответ 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).

Ответ 2

Swift 2.0 использует следующий синтаксис:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Обратите внимание, что теперь @param - parameter.

Теперь вы также можете включить в свою документацию маркеры:

/**
        - square(5) = 25
        - square(10) = 100
    */

Ответ 3

Senseful:

Вам может потребоваться создать проект до появления последних изменений в документации.

Иногда этого мне не хватало. Закрытие Xcode и открытие резервной копии проекта обычно устраняет эти случаи.

Я также получаю разные результаты в файлах .h и .m. Я не могу получить новые строки, когда комментарии к документации находятся в файле заголовка.

Ответ 4

Большая часть форматирования изменилась для 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.