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

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


2)
Само собой, поддерживаются стандартные теги @param
, @return
, а также некоторые другие, например, @note
, @warning
, @see
, @code
:
- (BOOL)doSomethingWithArgument:(NSString *)argument;

3)
Документировать можно не только отдельные методы, но и весь класс в целом:
@interface QHExample : NSObject

4)
Документирование свойств:
@property (nonatomic) int exampleProperty;

5)
Deprecated методы определяются автоматически:
- (void)someMethod __attribute__((deprecated("use '-anotherMethod' instead.")));

6)
Функции тоже поддерживаются:
int function_42(float fArg);

А макросы, к сожалению, — нет.
7)
Есть поддержка enum
:
enum ROUChunkType {
ROUChunkTypeData = 0,
ROUCHunkTypeAck = 1
};
Но нет поддержки рекомендуемых NS_ENUM
и NS_OPTIONS
.
Т.е. если записать:
typedef NS_ENUM(uint8_t, ROUChunkType){
ROUChunkTypeData = 0,
ROUCHunkTypeAck = 1
};
то для констант описания в Quick Help и в автодополнении будут доступны, но для самого типа ROUChunkType
— нет.

8)
Для типов-структур ситуация получше: для самого типа нет описания в автодополнении, но в Quick Help есть, для полей есть и то и то.
typedef struct {
enum ROUChunkType type;
uint16_t length;
} ROUChunkHeader;
9)
Зато хорошо работает документация для типов-блоков:
typedef BOOL (^QHBlock)(id arg);

10)
Кроме того, поддерживаются комментарии не только в интерфейсе, но и в реализации, в том числе для переменных:
- (double)perimeter{
double pi = M_PI;
return 2 * pi * self.r;
}

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

Тогда при наборе docmethod
автодополнение автоматически предложит соответствующий шаблон.
Автор: Yan169
Источник
Quick Help для своего кода в XCode 5
2013-09-03 в 3:55, admin, рубрики: comments, documentation, doxygen, iOS, mac os x, objective-c, xcode, документирование, комментарии, разработка под iOS, метки: comments, documentation, doxygen, iOS, mac os x, objective-c, xcode, документирование, комментарии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
автодополнение автоматически предложит соответствующий шаблон.Автор: Yan169
Источник
Рекомендованный контент