Quick Help for your code in Xcode 5

Quick Help has learned to take documentation from the comments:



Previously, it was necessary to install appledoc (or analog), compile and install .docset ; now it is enough just to write a documenting comment , and Quick Help will see it immediately.
There is no official documentation on the supported syntax yet (at least, I did not find it), but something is used in between HeaderDoc and Doxygen .

one)

The first paragraph of the comment is used in autocompletion, in Quick Help you can see everything:

 /** Brief description. Brief description continued. Details follow here. */ - (BOOL)doSomethingWithArgument:(NSString *)argument; 

')

2)

Of course, standard @param , @return tags are supported, as well as some others, for example, @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)

Not only individual methods can be documented, but the entire 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 

four)

Documenting properties:

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

five)

Deprecated methods are determined automatically:

 /** 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); 

And 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 the recommended NS_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 the constants, descriptions in Quick Help and in autocompletion will be available, but not for the ROUChunkType type ROUChunkType .

eight)

For structured types, the situation is better: for the type itself, there is no description in autocompletion, but in Quick Help there is, for fields, this and that.

 /** 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); 

ten)

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 documenting comments. Moreover, it is not at all labor-intensive if using 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 the shortcut docmethod :

Then when typing docmethod autocompletion will automatically suggest the corresponding template.