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

  • Tutorial
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 автодополнение автоматически предложит соответствующий шаблон.
Поделиться публикацией
Похожие публикации
AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама
Комментарии 21
  • +1
    Да наконец-то!

    Сам лично перешел на AppCode для работы с кодом. Она такое поддерживала еще, как минимум год назад.

    Надо сказать, что вообще, Apple в Xcode5 сделала много правильных шагов. Например, XIBы стали гораздо проще, прозрачнее и понятнее. Теперь задача мержа двух XIBов из разных веток видится уже более или менее реальной.

    И тот факт, что в Xcode5 появилась поддержка режима CI сервера для Apple является огромным шагом вдогонку современным технологиям. Я для CI использую Jenkins + скрипты и xcode plugin в для прогона тестов. Но этот плагин меня не полностью устраивает.
    • 0
      А не подскажете, какой формат документации наиболее «правильный» для AppCode? А то с JavaDoc-подобным иногда косяки бывают.
      • 0
        Что-то похожее на JavaDoc (но не полный, например, не работает return). Думаю, что теперь, поскольку этот функционал заработал в Xcode, JetBrains приведет его в соответствие с вариантом от Apple.
        • 0
          Вот да, с return и проблемы как раз. Спасибо за ответ!
      • 0
        CI в Xcode5 мягко говоря, очень убог и абсолютно не кастомизируем.
        • 0
          Ну я, надеюсь, что это у них только первый шаг. Впрочем, меня сейчас почти полность устраивает Jenkins.
        • 0
          > Я для CI использую Jenkins + скрипты и xcode plugin в для прогона тестов.

          А тесты для OS X или iOS? Так и не нашел варианта для запуска тестов iOS — все портит необходимость запускать сперва симулятор, а потом в нем запускать приложение.
          • 0
            Модульные тесты для iOS. Вообще прогнать модульные тесты на симуляторе проблем нет. xcode-build все умеет. Лично для меня плагин нужен только для того, чтобы распарсить полученный выхлоп в формат, понятный Jenkins'у.
            • 0
              у xctool вывод поприятнее будет :)
            • 0
              Вот эта вещь может вам пригодиться.
        • +4
          Также можно включить флаг -Wdocumentation и будет проверяться соответствие комментария объявлению, насколько это возможно автоматически. Например, будет выдаваться предупреждение при @param для несуществующего параметра функции.
          • 0
            А как раньше код документировался в XCode? Были какие-то стандарты? Я, собственно, почему спрашиваю — в Java есть JavaDoc, который идёт «из коробки». А тут получается ничего подобного не было?
          • 0
            А разве информация о XCode 5 пока не под NDA?
            • +1
              Информация о том, что Quick Help теперь поддерживает документирующие комментарии, доступна на открытой странице developer.apple.com/technologies/tools/features.html:
              Quick Help
              Displays shortened API documentation while your are programming, including comments that you write for your own code.
              • 0
                Вот оно как.
                Извиняюсь, не знал.
            • 0
              Стоит так же упомянуть о замечательном плагине упрощающем писать такую документацию github.com/onevcat/VVDocumenter-Xcode
              • 0
                Недавно как-раз на эту тему задавал хабра-вопрос :)
                • 0
                  Совсем недавно смотрел видео с последней WWDC и видел отсылку к Doxygen. (Xcode Core Concepts, 29:50), так что скорее всего его и юзают
                  • 0
                    У Clang какой-то свой парсер документации AFAIK

                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.