Xcode code documentation

Question

Are there any guidelines/standards about how to document the code written in XCode? I mean, is there a way to document the code if you want to make it easily understandable to others? Does XCode provide an instrument that can be used to automatically produce documentation like the API reference docs from your code+comments?

At least I'm interested in understanding if there is a standard way of writing comments before interfaces/protocols/methods defined in your code. I've seen using directives like the following one, but I did not understand how they work:

#pragma mark -
#pragma mark Initialization

Answer 1

You can merge those two lines in one: #pragma mark - Initialization. Click on the method list (up, right) and you'll see a bold header with a line. It's just a marker to group methods in sections.

The Coding Guidelines link posted by Derek above is a must read.

If you want to produce Apple-like documentation you have to use this excellent and free third party tool: http://www.gentlebytes.com/appledoc/ Apple doesn't provide you with anything close to that.

---

Pragmas are a ISO C feature to pass hints to the compiler.

The only pragma addition in XCode (AFAIK) is mark with - and/or text. This creates a line and/or bold text in the method finder.

// Mark a section in your code with a line and a bold text.
// You can use the line or the text alone.
#pragma mark - random text

If you are editing files on languages which don't compile with GCC, you still can use mark on comments (this works for GCC languages too):

// MARK: - random text
/* MARK: more random text */

But I use #pragma mark because my color theme has pragmas in red and they stand out better than comments. If you want a pragma code snippet binded to a hotkey, use

#pragma mark - <#Description#>

so you can tab jump to the description text.

More about pragmas:

• What is a pragma?
• 6.56 Pragmas Accepted by GCC
• Clang's Controlling Diagnostics via Pragmas
• Function attributes are preferred to pragmas because you can't generate pragmas from macros and a pragma might have a different meaning on another compiler.

Answer 2

Adding to @jano's answer, use below format to describe the functionality of your method.

  /*!
 @function       getEmployeeDetails
 @abstract       getEmployeeDetails
 @discussion     This function will fetch employee details based on employee id
 @param          strEmpId 
 employee unique id
 @result         an Array of Employee
 */

-(NSArray*)getEmployeeDetails:(NSString *)strEmpId{
     /*Do somethings.*/
}