Одной из новых функций Xcode 5 является возможность документировать свой собственный код со специальным синтаксисом комментариев. Формат похож на doxygen, но, похоже, поддерживает только подмножество этих функций .

Какие команды поддерживаются, а какие нет?
Отличается ли их использование от doxygen?

Вот пример всех вариантов, которые я нашел с 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).

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

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.