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

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

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

Источник

4 ответа

Решение

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

Источник
Другие вопросы по тегам