Quick Help for your code in Xcode 5

  • Tutorial
Quick Help learned to take documentation from comments:



Previously, you had to install appledoc (or an analogue), compile and install it .docset; Now just write a documentary comment and Quick Help will immediately see it.
There is no official documentation on the supported syntax yet (at least I have not found), but something is used between HeaderDoc and Doxygen .

1)

The first paragraph of the comment is used in autocompletion, in Quick Help everyone is visible:
/**
 Brief description.
 Brief description continued.
 Details follow here.
 */
- (BOOL)doSomethingWithArgument:(NSString *)argument;




2)

Of course, supported by the standard tags @param, @returnas well as some others, such as @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)

You can document not only individual methods, but the whole class as a whole:
/**
 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)

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



5)

Deprecated methods are automatically determined:
/**
 This method is deprecated!
 @see '-anotherMethod'
 */
- (void)someMethod __attribute__((deprecated("use '-anotherMethod' instead.")));



6)

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


But macros, unfortunately, are not.

7)

There is support for enum:
/**
 ROUChunkType description.
 */
enum ROUChunkType {
    /// Data chunk.
    ROUChunkTypeData = 0,
    /// Acknowledgement chunk.
    ROUCHunkTypeAck = 1
};

But there is no support for recommendedNS_ENUM and NS_OPTIONS.
Those. if you write:
/**
 ROUChunkType description.
 */
typedef NS_ENUM(uint8_t, ROUChunkType){
    /// Data chunk.
    ROUChunkTypeData = 0,
    /// Acknowledgement chunk.
    ROUCHunkTypeAck = 1
};

then for constants descriptions in Quick Help and in autocompletion will be available, but for the type itself ROUChunkType- not.


8)

For structure types, the situation is better: for the type itself, there is no description in the auto-completion, but in Quick Help there is, for fields there is both.
/**
 Chunk header description.
 */
typedef struct {
    /// Chunk type.
    enum ROUChunkType type;
    /// Chunk length.
    uint16_t length;
} ROUChunkHeader;


9)

But the documentation for block types works well:
/**
 A block with one argument returning BOOL.
 @param arg Block's argument.
 @return YES.
 */
typedef BOOL (^QHBlock)(id arg);



10)

In addition, comments are supported not only in the interface, but also in the implementation, including for variables:
- (double)perimeter{
    /// The number π, the ratio of a circle's circumference to its diameter.
    double pi = M_PI;
    return 2 * pi * self.r;
}



Conclusion

In total, it became one more reason to write documentary comments. Moreover, this is not at all laborious if you use code snippets . For example, to document a method, you can create a snippet:
/**
 <#Brief#>
 <#Description#>
 @param <#Name#> <#Info#>
 @param <#Name#> <#Info#>
 @return <#Returns#>
 */

and hang it on a shortcut docmethod:

Then, when typing, docmethodauto-completion will automatically offer the appropriate template.

Also popular now: