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 автодополнение автоматически предложит соответствующий шаблон.

This entry passed through the Full-Text RSS service — if this is your content and you're reading it on someone else's site, please read the FAQ at fivefilters.org/content-only/faq.php#publishers. Five Filters recommends:

• Massacres That Matter - Part 1 - 'Responsibility To Protect' In Egypt, Libya And Syria


• Massacres That Matter - Part 2 - The Media Response On Egypt, Libya And Syria


• National demonstration: No attack on Syria - Saturday 31 August, 12 noon, Temple Place, London, UK