CODEWITHSUNDEEP
objective-cxcodedocumentationcomments
Oliver Dixon
Oliver Dixon

Reputation: 7414

Objective-C method description (doc comments)

I'm currently learning Objective-C and need to know how to write a method description. I'm having a lot of difficulty learning how to do this in Objective-C.

In Jave we have this

/**
< h2 >MethodName</ h2 >
< p >Various Description, can use html with images etc.</ p >
*/
private void methodName(args[]..)
{

}

In objective-c where do I place the description? Also does this to be in the header file or the implementation file?

//Within Implementation?
- (float)gteHeightPercentage:(float)percentageToGet
{
    return self.view.bounds.size.height * percentageToGet;
}

//Within Header?
- (float)getWidthPercentage:(float)percentageToGet;

Upvotes: 26

Views: 25579

Answers (3)

Q8i
Q8i

Reputation: 1787

Update: The format below works for Objc. If you want to document swift code, refer to NSHipster's blog about Swift Documentation

The Xcode 5 can do what you want. Thanks to Wonil Kim, in the .h file:

/** 
 * Add new message between source to destination timeline as empty name string
 * @author Wonil Kim
 *
 * @param sourceId Source timeline entity ID
 * @param destId Destination timeline entity ID
 * @return A newly created message instance
 */
- (ISMessage*)messageFromTimeline:(NSInteger)sourceId toTimeline:(NSInteger)destId;

Once this is done, you can alt+click on the method name, and.. voilà!

Of course, as you can see on Kim's blog, this is not the only way:

/*! Some description of the method....
 * \returns  The result
 */

Alternatively,

/// Some description to show up, done by:
/// @author  Olly Dixon

You got the point...

As many already have mentioned, Objective-C does not show you your documentation; in fact, neither does java (javadoc, may be). It's your IDE, in this case, the un-crashable Xcode :)

UPDATE2: Complete list of "Special Commands" in comments.

UPDATE3: Use VVDocumenter-Xcode if you'd like to enable auto-generation of documentation by ///.

UPDATE4:: VVDocumenter has be integrated in to Xcode:

Use the shortcut (⌥ Option + ⌘ Command + /) to add a documentation comment to your code if you are using Xcode 8 or above

Upvotes: 74

Caleb
Caleb

Reputation: 125007

In objective-c where do I place the description?

Objective-C compilers like gcc and llvm don't care how you document your code. There are several different documentation generators such as Doxygen and HeaderDoc that can build documentation from appropriately formatted comments, usually in your header files. Additionally, Xcode makes it easy to jump to the definition of symbols defined in your code, and it's "quick help" inspector can show you definitions, both without any special annotations in your code.

Upvotes: 0

rob mayoff
rob mayoff

Reputation: 385680

What you are describing are called “documentation comments”, or “doc comments” for short.

Xcode, as of version 4.6.3, does not display your own doc comments in a pop-up window or its quick help inspector. You have to compile your comments into a “docset” to get Xcode to display them. There are tools to do that, but there is no way to get Xcode to reload a docset except by quitting and restarting it, so I don't recommend bothering.

Xcode 5 (which is currently available as a developer preview for paid members of the OS X and iOS developer programs) does display the doc comments for your own code; see “Quick Help” on the Developer Tools Features page. You must write the doc comments in the header file. You may use either doxygen or headerdoc format.

Upvotes: 6

Related Questions