Objective-C описание метода (комментарии doc)

В настоящее время я изучаю Objective-C и должен знать, как написать описание метода. Мне трудно понять, как это сделать в Objective-C.

В Jave мы имеем это

/**
< h2 >MethodName</ h2 >
< p >Various Description, can use html with images etc.</ p >
*/
private void methodName(args[]..)
{

}

В Objective-C, где разместить описание? Также это должно быть в файле заголовка или в файле реализации?

//Within Implementation?
- (float)gteHeightPercentage:(float)percentageToGet
{
    return self.view.bounds.size.height * percentageToGet;
}

//Within Header?
- (float)getWidthPercentage:(float)percentageToGet;

Ответ 1

Обновление: формат ниже работает для Objc. Если вы хотите задокументировать код swift, обратитесь к блогу NSHipster о документации Swift.

XCode 5 может делать то, что вы хотите. Спасибо Вонилу Киму, в файле .h:

/** 
 * Add new message between source to destination timeline as empty name string
 * @author Wonil Kim
 *
 * @param sourceId Source timeline entity ID
 * @param destId Destination timeline entity ID
 * @return A newly created message instance
 */
- (ISMessage*)messageFromTimeline:(NSInteger)sourceId toTimeline:(NSInteger)destId;

Как только это будет сделано, вы можете alt +click на имя метода, и.. вуаля!

Конечно, как вы можете видеть в блоге Kim, это не единственный способ:

/*! Some description of the method....
 * \returns  The result
 */

С другой стороны,

/// Some description to show up, done by:
/// @author  Olly Dixon

Вы поняли...

Как уже упоминали многие, Objective-C не показывает вашу документацию; на самом деле, также как и Java (Javadoc, может быть). Это ваша IDE, в данном случае неразрушимый Xcode :)

ОБНОВЛЕНИЕ 2: Полный список "Специальные команды" в комментариях.

ОБНОВЛЕНИЕ 3: Используйте VVDocumenter-Xcode, если вы хотите включить автоматическую генерацию документации по ///.

UPDATE4:: VVDocumenter был интегрирован в Xcode:

Используйте ярлык (⌥ Option + ⌘ Command +/), чтобы добавить комментарий документации к вашему коду, если вы используете Xcode 8 или выше

Ответ 2

То, что вы описываете, называется "комментариями к документации" или "комментариями к документу" для краткости.

Xcode, начиная с версии 4.6.3, не отображает ваши собственные комментарии к документам во всплывающем окне или его операторе быстрой справки. Вы должны скомпилировать свои комментарии в "docset", чтобы получить Xcode для их отображения. Есть инструменты для этого, но нет способа заставить Xcode перезагрузить docset, кроме как выйти и перезапустить его, поэтому я не рекомендую беспокоиться.

Xcode 5 (который в настоящее время доступен как предварительный просмотр разработчика для платных членов программ для разработчиков OS X и iOS) делает отображение комментариев к вашему коду; см. "Быстрая справка" на странице "Возможности разработчика" . Вы должны написать комментарии в файле заголовка. Вы можете использовать либо doxygen, либо формат headerdoc.

Ответ 3

В objective-c, где разместить описание?

Objective-C компиляторы, такие как gcc и llvm, не заботятся о том, как вы документируете свой код. Существует несколько разных генераторов документации, таких как Doxygen и HeaderDoc, которые могут создавать документацию из должным образом отформатированных комментариев, обычно в ваших файлах заголовков. Кроме того, Xcode позволяет легко перейти к определению символов, определенных в вашем коде, и инспектор "быстрой справки" может показать вам определения, оба без каких-либо специальных комментариев в вашем коде.