Quick Help для своего кода в XCode 5

Quick Help научился брать документацию из комментариев:

Раньше нужно было ставить appledoc (или аналог), компилировать и устанавливать .docset; теперь же достаточно просто написать документирующий комментарий, и Quick Help сразу его увидит.
Официальной документации по поддерживаемому синтаксису пока нет (по крайней мере, я не нашел), но используется что-то среднее между HeaderDoc и Doxygen.

1)

Первый абзац комментария используется в автодополнении, в Quick Help видны все:

/**  Brief description.  Brief description continued.    Details follow here.  */ - (BOOL)doSomethingWithArgument:(NSString *)argument; 

2)

Само собой, поддерживаются стандартные теги @param, @return, а также некоторые другие, например, @note, @warning, @see, @code:

/**  Brief description.  Brief description continued.    Details follow here.    @note I am a note!    @warning Not thread safe!    @param argument Some string.    @return YES if operation succeeded, otherwise NO.  */ - (BOOL)doSomethingWithArgument:(NSString *)argument; 

3)

Документировать можно не только отдельные методы, но и весь класс в целом:

/**  Example class to show the new cool XCode 5 feature.    Usage example:  @code  QHExample *example = [QHExample new];  BOOL result = [example doSomethingWithArgument:@"test"];  @endcode  */ @interface QHExample : NSObject 

4)

Документирование свойств:

/// Description for exampleProperty. @property (nonatomic) int exampleProperty; 

5)

Deprecated методы определяются автоматически:

/**  This method is deprecated!    @see '-anotherMethod'  */ - (void)someMethod __attribute__((deprecated("use '-anotherMethod' instead."))); 

6)

Функции тоже поддерживаются:

/**  A function that always returns 42.    @param fArg Some float argument.    @return 42.  */ int function_42(float fArg); 

А макросы, к сожалению, — нет.

7)

Есть поддержка enum:

/**  ROUChunkType description.  */ enum ROUChunkType {     /// Data chunk.     ROUChunkTypeData = 0,     /// Acknowledgement chunk.     ROUCHunkTypeAck = 1 }; 

Но нет поддержки рекомендуемых NS_ENUM и NS_OPTIONS.
Т.е. если записать:

/**  ROUChunkType description.  */ typedef NS_ENUM(uint8_t, ROUChunkType){     /// Data chunk.     ROUChunkTypeData = 0,     /// Acknowledgement chunk.     ROUCHunkTypeAck = 1 }; 

то для констант описания в Quick Help и в автодополнении будут доступны, но для самого типа ROUChunkType — нет.

8)

Для типов-структур ситуация получше: для самого типа нет описания в автодополнении, но в Quick Help есть, для полей есть и то и то.

/**  Chunk header description.  */ typedef struct {     /// Chunk type.     enum ROUChunkType type;     /// Chunk length.     uint16_t length; } ROUChunkHeader; 

9)

Зато хорошо работает документация для типов-блоков:

/**  A block with one argument returning BOOL.    @param arg Block's argument.    @return YES.  */ typedef BOOL (^QHBlock)(id arg); 

10)

Кроме того, поддерживаются комментарии не только в интерфейсе, но и в реализации, в том числе для переменных:

- (double)perimeter{     /// The number π, the ratio of a circle's circumference to its diameter.     double pi = M_PI;          return 2 * pi * self.r; } 

Заключение

Итого, стало на одну причину больше писать документирующие комментарии. Тем более, это совсем не трудозатратно, если использовать code snippets. Например, для документирования метода можно создать сниппет:

/**  <#Brief#>    <#Description#>    @param <#Name#> <#Info#>  @param <#Name#> <#Info#>    @return <#Returns#>  */ 

и повесить его на шорткат docmethod:

Тогда при наборе docmethod автодополнение автоматически предложит соответствующий шаблон.