HeaderDoc was added in Xcode 5.0 release and with iOS 7.0.
HeaderDoc is a nice command tool that a developer can use to automatically generate nice HTML documentation of the code as long as the code comments are in a particular structured way.
In addition, Xcode also parses the HeaderDoc style comments behind the scenes to automatically present the documentation in quick look panels.
There are three styles of comments that HeaderDoc scans for.
Option 1:
/// The documentation goes here
Option 2:
/**
* The documentation goes here
*/
Option 3:
/*!
* The documentation goes here
*/
All three result in same if the documentation is done in Xcode.
Below could be one approach we can follow in documenting
1. Use /*! … */ for large code block comments
2. Use /// for Single line comment for smaller code comments
HeaderDoc tags
Once the headerdoc finds a comment in one of the above styles, it will search that comment for tags for more information. There are two types of tags, Top-Level tags and Second Level tags
Esmple of top level tag is @typedef. These define type of things we are commenting for e.g. Headers, classes, methods etc.
Second level tags help to give more details about specific things we are commenting
Few main tags in second level comments are @brief, @discussion, @abstract, @param, @return. This is not complete set of tags and the complete set can be found at the apple website given in the references
Documenting Properties
For documenting properties, it is just sufficient to have brief keyword, example like below
/*!
* @brief This is documentation of a property.
*/
After documenting the properties,
Documenting methods.
Below documentation provides a good information to the user. @brief tells description of the method, @param indicates the parameter list,
/*!
* @brief Adds a notification to the notification list locally.
* Once a notification is added, the notification properties will contain the
* key kMPNotificationSource property set to "local" indicating this is a
* locally generated notification.
*
*
* @param properties : Properties of a notification to be added.
* @return If the notification is added successfully the return value will be nil
* If could not, the NSError object will be returned describing the error.
*/
In Xcode, the above appears like the below screenshot upon Option + Click
In case if there is a warning to be added, @warning tag can be used. After this change, the method will look like this below.
/*!
* @brief Adds a notification to the notification list locally.
* Once a notification is added, the notification properties will contain the
* key kMPNotificationSource property set to "local" indicating this is a
* locally generated notification.
*
* @warning the properties dictionary must not be nil.
*
* @param properties : Properties of a notification to be added.
* @return If the notification is added successfully the return value will be nil
* If could not, the NSError object will be returned describing the error.
*/
References:
No comments:
Post a Comment