Однією з нових можливостей Xcode 5 є можливість документувати власний код за допомогою синтаксису спеціального коментаря. Формат схожий на доксиген, але, здається, підтримує лише підмножину цих функцій .

Які команди підтримуються, а які ні?
Чи відрізняється будь-яке їх використання від доксигену?

Ось приклад усіх варіантів, які я знайшов у 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. У доксигені

Оскільки команди в Xcode 5 сумісні з Doxygen, ви можете завантажити та використовувати Doxygen для створення файлів документації.

Інші примітки

Що стосується загального вступу до Doxygen та способу документування коду Objective-C, ця сторінка здається непоганим ресурсом.

Описи деяких підтримуваних команд:

• @brief: вставить текст на початку поля опису, і це єдиний текст, який з’явиться під час заповнення коду.

Нижче не працює:

• \n: не створює новий рядок Один із способів створити нову лінію - переконатися, що нічого немає на цій лінії. Навіть жодного космічного персонажа!
• \example

Наступні не підтримуються (вони навіть не відображаються темно-зеленим):

• \ цитувати
• \ docbookonly
• \ enddocbookonly
• \ кінцевий
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ повторно
• \ пов'язані також
• \ rtfonly
• \ секрет
• \ короткий
• \ фрагмент
• \зміст
• \ vhdlflow
• \ ~
• \ "
• .
• ::
• \ |

Apple зарезервовані ключові слова:

Apple використовує ключові слова, які видаються зарезервованими, і це працює лише в їх документації. Хоча вони з'являються у темно-зеленому кольорі, схоже, ми не можемо використовувати їх так, як Apple. Ви можете побачити приклади використання Apple у таких файлах, як AVCaptureOutput.h.

Ось список деяких із цих ключових слів:

• @ab абстракт, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref.

У кращому випадку ключове слово спричинить новий рядок у полі Опис (наприклад, @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
    */

Чуттєвий:

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

Іноді цього мені було недостатньо. Закриття 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.