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?

http://stackoverflow.com/questions/813529/documentation-generator-for-objective-c — Dyno Fu, Sep 21 '11 at 02:39
Thanks for the quick reply. I know how to comment in the code, but was wondering if there was a specific format for commenting above methods to explain what the method does. I want to be able to click the method implementation and have it display what the method does. Can you make comments that show in the Quick Help, such as filling in the abstract and return value? — Jonathan, Sep 21 '11 at 02:39
appledoc - Objective C API documentation generator http://www.gentlebytes.com/home/appledocapp/ — Dyno Fu, Sep 21 '11 at 02:40

bryanmac · Answer 1 · 2013-05-21T11:58:06.427

19

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:

enter image description here

edited May 21 '13 at 11:58

answered Sep 21 '11 at 03:31

bryanmac

38,941
11
91
99

no need to write seperate lines for this just a single line would do.See my answer – Lithu T.V May 17 '13 at 06:28
Yes, but I add the extra lines intentionally so it's a big block to break up the source file. Beyond getting the dropdown, I want to be able to scroll the the file and see it visually divided. – bryanmac May 21 '13 at 11:57

zaph · Answer 2 · 2011-09-21T02:45:14.583

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.

score 9 · Answer 3 · answered Sep 21 '11 at 02:39

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

Doxygen style for multi-line comments and the like is `/** ... */`. — , Sep 21 '11 at 03:15

score 4 · Answer 4 · answered May 17 '13 at 06:27

How I do is like this,

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

score 1 · Answer 5 · answered Apr 24 '14 at 08:14

1

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

this is displayed on quick help

thinks

answered Apr 24 '14 at 08:14

allan

21
2

This does not provide an answer to the question. To critique or request clarification from an author, leave a comment below their post - you can always comment on your own posts, and once you have sufficient [reputation](http://stackoverflow.com/help/whats-reputation) you will be able to [comment on any post](http://stackoverflow.com/help/privileges/comment). – Srini V Apr 24 '14 at 08:57
I'm Chinese . english is poor so that I don't know you means~ ____To critique or request clarification from an author – allan Apr 24 '14 at 09:41

score 0 · Answer 6 · answered Sep 21 '11 at 03:07

0

You would use

//for a single line comment
/*Use this for the start of a block comment
*/Use this for the end of a comment
   /*text text text;
   code code;
   code code code;//comment
   code;//comment
   code;*/

answered Sep 21 '11 at 03:07

user891123

379
2
5
16

Objective-C Method Comments

6 Answers6