Что такое комментарии к документации в Xcode?

Ответ 1

Не стесняйтесь повышать этот ответ.

Комментарии к документации - это просто (Objective-C) комментарии, помеченные как документация. Их обрабатывают так же, как и обычные комментарии, за исключением того, что вы можете установить другой цвет и шрифт в Xcode. Некоторое программное обеспечение документации может даже использовать эти комментарии для создания автоматической документации из заданных файлов заголовков и другого исходного кода.

Ключевые слова комментариев к документации - это ключевые слова, которые дают семантическое значение для текста, следующего за ключевым словом в комментарии к документации.

Вы можете создавать встроенные комментарии к документации с тремя сокращениями (вместо двух в обычных комментариях) и блоком doc. комментарии с двумя звездами вместо одного (вместо одного в обычных комментариях). Пример:

// Normal inline comment
/// Documentation comment

/* Normal block
comment */
/** Documentation block
comment */

Вы можете создать ключевые слова комментариев к документации, указав ключевое слово (только одно слово) после символа "at". Пример:

- (void)sendMessage: (id)sender;
/// @description Sends the receiver.
/// @available Version 1.0 through 2.2

Appledoc - это инструмент для создания набора документации из исходного кода (включая комментарии к документации и подписи метода) и его установку и перезагружайте внутри Xcode, когда это необходимо. Это программа командной строки и содержит инструкции по ее включению в процесс сборки Xcode.

После того, как у вас есть набор документации, вы можете добавить его в Xcode через Настройки > Загрузки > Документация.

Специальные ключевые слова, начинающиеся с @-sign, также называются тегами HeaderDoc. Список их можно найти в руководстве пользователя HeaderDoc. Обратите внимание, что некоторые из них Objective-C, а некоторые - С++.

Ответ 2

Для тех, кто не смотрел последнюю заметку: с Xcode 5 эта функция будет встроена. Она уже доступна в текущем предварительном просмотре разработчика (называется быстрой справкой, например объявленной здесь).

Ответ 3

Xcode 5 теперь имеет встроенную поддержку комментариев в стиле Oxygen. Итак, вы можете прокомментировать ваши методы следующим образом:

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;

Встроенная справка будет выглядеть так:

в

Быстрая справка будет выглядеть так:

в

И помощь боковой панели будет выглядеть так:

Вот удобный фрагмент кода, который вы можете добавить в библиотеку Xcode Code Snippet, чтобы упростить документацию по методу:

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

Теперь вы можете просто ввести "doxy" и poof! У вас есть шаблон doxygen.

Ответ 4

Существует несколько таких инструментов, как Doxygen, Javadoc и другие, которые признают "особые" комментарии (известные как комментарии к документации) для автоматической генерации документации для кода.

Как правило, комментарии к документации начинаются со специальной последовательности, такой как /** (в отличие от просто /*) и содержат специальные ключевые слова, которые часто имеют специальный стартовый символ, такой как @. Существует много сходств между различными генераторами документации комментариев, большинство из которых принимают параметры "@param" для документирования параметров "@return" для возврата значений документа, "@throws" для документирования исключений и т.д.

В контексте подсветки синтаксиса Xcode комментарии к документации - это те, в которых одна из этих специальных начальных последовательностей распознается Xcode. Следует отметить, что существует определенный набор таких комментариев, которые Xcode правильно распознает; например, инструмент Doxygen также позволяет /*! а также //! (с восклицанием), чтобы указать начало комментариев к документации, но Xcode не распознает его.