html текст
All interests
  • All interests
  • Design
  • Food
  • Gadgets
  • Humor
  • News
  • Photo
  • Travel
  • Video
Click to see the next recommended page
Like it
Don't like
Add to Favorites

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

материал с habrahabr.ru

1

      Add

      You can create thematic collections and keep, for instance, all recipes in one place so you will never lose them.

      No images found
      Previous Next 0 / 0
      500
      • Advertisement
      • Animals
      • Architecture
      • Art
      • Auto
      • Aviation
      • Books
      • Cartoons
      • Celebrities
      • Children
      • Culture
      • Design
      • Economics
      • Education
      • Entertainment
      • Fashion
      • Fitness
      • Food
      • Gadgets
      • Games
      • Health
      • History
      • Hobby
      • Humor
      • Interior
      • Moto
      • Movies
      • Music
      • Nature
      • News
      • Photo
      • Pictures
      • Politics
      • Psychology
      • Science
      • Society
      • Sport
      • Technology
      • Travel
      • Video
      • Weapons
      • Web
      • Work
        Submit
        Valid formats are JPG, PNG, GIF.
        Not more than 5 Мb, please.
        30
        surfingbird.ru/site/
        RSS format guidelines
        500
        • Advertisement
        • Animals
        • Architecture
        • Art
        • Auto
        • Aviation
        • Books
        • Cartoons
        • Celebrities
        • Children
        • Culture
        • Design
        • Economics
        • Education
        • Entertainment
        • Fashion
        • Fitness
        • Food
        • Gadgets
        • Games
        • Health
        • History
        • Hobby
        • Humor
        • Interior
        • Moto
        • Movies
        • Music
        • Nature
        • News
        • Photo
        • Pictures
        • Politics
        • Psychology
        • Science
        • Society
        • Sport
        • Technology
        • Travel
        • Video
        • Weapons
        • Web
        • Work

          Submit

          Thank you! Wait for moderation.

          Тебе это не нравится?

          You can block the domain, tag, user or channel, and we'll stop recommend it to you. You can always unblock them in your settings.

          • habrahabr.ru
          • домен habrahabr.ru

          Get a link

          Спасибо, твоя жалоба принята.

          Log on to Surfingbird

          Recover
          Sign up

          or

          Welcome to Surfingbird.com!

          You'll find thousands of interesting pages, photos, and videos inside.
          Join!

          • Personal
            recommendations

          • Stash
            interesting and useful stuff

          • Anywhere,
            anytime

          Do we already know you? Login or restore the password.

          Close

          Add to collection

             

            Facebook

            Ваш профиль на рассмотрении, обновите страницу через несколько секунд

            Facebook

            К сожалению, вы не попадаете под условия акции