An example class in Objective-C with comments prepared specifically for generating documentation from code using tool called appledoc: http://gentlebytes.com/appledoc/

gistfile1.m

//
//  ExampleClass.h
//
//  Created by Sebastian Ewak on 5/17/13.
//
#import <Foundation/Foundation.h>


/** Example class for appledoc documentation generation tool commenting style guidelines.

  Paragraphs should be delimited by a page break.
 
  Emphsing a word is done like this `Some emphasised word`.
 
  You can make an: (note that there needs to be 

  - unordered
  - list
  - like
  - this
 
  You can also make an:
 
  1. ordered
  2. list
  3. like
  4. this
 
  Indents should be made with UP TO 3 SPACES to have normal test like this one.
 
    If you want to have some text enclosed with block like this one use MORE THAN 3 SPACES.
*/
@interface ExampleClass : NSObject

///---------------------------------------------------------------------------------------
/// @name Strong properties
///---------------------------------------------------------------------------------------

/** 
 This is some text property 
*/
@property (nonatomic, strong) NSString *textProperty;

/** This is some number property */
@property (nonatomic, strong) NSNumber *numberProperty;

///---------------------------------------------------------------------------------------
/// @name Weak properties
///---------------------------------------------------------------------------------------

/** This is some NSObject */
@property (nonatomic, weak) NSObject *someObject;
/** This is some other NSObject */
@property (nonatomic, weak) NSObject *someOtherObject;

///---------------------------------------------------------------------------------------
/// @name Instance methods
///---------------------------------------------------------------------------------------

/** Returns number of characters in the given `stringParamter` with `numberParemeter` added to it.
 
 This is some text that will only be shown in the discussion section of method documentation. *If you want text in italics enclose it in asterixes.*
 
 @param stringParameter String which number of characters will be outputed by the method.
 @param numberParameter Number which will be added to the returned string character count.
 
 @return number of characters in the given `stringParamter` with `numberParemeter` added to it
 
 @note I didn't write this method so I don't really know what it does...

 @warning Returns `NaN` if `numberParemeter` is nil.
 
 @exception NSSomeException Thrown when `stringParamter` is nil.\
 
 @see someObject, someOtherObject, someMethodWithObject:
 @see textProperty
 @see numberProperty
*/
- (double)someMethodWithString:(NSString *)stringParameter withNumber:(NSNumber *)numberParameter;

/** Some other method that does nothing really.
    
    It takes one parameter and probably does something with it as otherwise it would be pretty useless...
 
    @param objectParameter Some object that will (*I hope*) be somehow processed by the method. It's such a drag to write those example comments...
*/
- (void)someMethodWithObject:(NSObject *)objectParameter;


@end