Objective-C Method Comments

Question

What is the proper way to comment methods for Objective-C? For example, in .Net I would add a xml comment like:

/// <summary>
/// Summary of method
/// </summary>
/// <param name="FileName">The document's original filename.</param>  
/// <returns>Decoded filename</returns>  

Is there an equivalent for Objective-C?

Answer 1

Don't forget about pragma marks for blocking your code. It helps XCode segregate the methods in the dropdown. It also visually breaks up your source file and makes it easier to read.

Here's how I block sections of code:

///////////////////////////////////////////////////////////////////////////
#pragma mark -
#pragma mark View Lifecycle
#pragma mark -
///////////////////////////////////////////////////////////////////////////

- (void) functionsHere

It ends up doing this in XCode:

Answer 2

There are appledoc header docs that can be used, the same ones Apple uses.

For individual methods the best guide is to use very descriptive names, this is rather easy in Objective-C with the parameters interspersed in the method name. This generally obviates the need for individual parameter comments.

As in any language descriptive method names and short single purpose methods beats lengthily comments that age poorly as code changes.

Answer 3

The style of commenting you mention seems to be the kind that a documentation generator picks up to generate documentation for you.

The equivalent style of commenting on objective-c would therefore be dependent on the documentation generator you choose. There is no default one as far as I know.

You can use something like Doxygen, or appledoc if you want something that gives results similar to Apple's own developer documentation. This page details the commenting format. Example: GBComment.h

Answer 4

How I do is like this,

//-----------------------------------------------------------------------------------------------------//
#pragma mark - Table view Datasource -
//-----------------------------------------------------------------------------------------------------//

Answer 5

/**
*   @brief  set refresh datetime
*
*   @param  value of refresh datetime
*
*   @return
*
*/

this is displayed on quick help

thinks