Какие новые команды документации доступны в Xcode 5? [закрыто]

186

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

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

Senseful
источник

Ответы:

419

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

Senseful
источник
4
Спасибо за описание. Надеюсь, Apple скопирует его в руководство по Xcode;)
TheGrumpyCoda
3
Использование символа @ вместо \ также работает.
Drewsmits
8
+1 Отличная коллекция! Как добавить ссылку на быструю помощь другого класса в быстрой справке?
Селвин
3
Вы также можете использовать @cдля отображения следующего слова в тексте пишущей машинки, как в Returns an @c NSString or @c nil..
Мэтью Кирос
7
Нашли ли вы способ, чтобы URL-адрес появлялся во всплывающем окне «Option»? Например, если вы щелкнете по Option -[CADisplayLink addToRunLoop:forMode:], описание будет включать в себя именованные ссылки на другие классы (но я полагаю, что URL-адреса в Интернете также будут полезны).
Зев Айзенберг
16

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
источник
9

Senseful:

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

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

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

weezma2004
источник
5

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

рукавицы
источник