Now that Xcode 5 supports doxygen annotation, it’s time for you to start using it!

Ever since Xcode 5 added native support for doxygen, it really pays to annotate your code with doxygen style comments, which only require a few extra characters to comments you may already make.

In looking for tips and tricks, I turned up an excellent how-to written 4 years ago (but still correct) that offers many different techniques. For example, you can remind yourself (and others) how to use a particular variable:

 @property(assign) int ts; ///< Short Comment

or line wrap for up to 3 lines of comments:

@property(assign) int ts; ///< Set the complete ...
                          ///< the progress ...

If you’d rather use C-style comments you can:

@property(assign) int ts; /**< Set the complete ...
                               the progress ... */

The parser seems really smart about how finding continuation comments and also ignoring leading white space. In my examples, I indented the second lines, but you can leave them pegged to the left margin if you prefer.

The more common doxygen usage is to provide annotation blocks above methods, and the oodles of options you can use to do that can be found in this recent post on StackOverFlow (make sure to upvote the question and answer!):

You can add this handy code snippet to your Xcode Code Snippet library:

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

as detailed here (and I just did!):

From then on you and others can get help during autocomplete, as well as by option-clicking on a method. I was slow to start using this, but now its getting to be second nature.

Also, if you start posting your open source code (using podspecs) to Cocoapods, they run doxygen on your files and create really nice documentation for them on CocoaDocs.

Advertisements

Using Markdown for READMEs in Open Source projects

On github, virtually all projects provide a README.md file (the “.md” denotes the file as type ‘Markdown’). Markdown is a means to easily style text without having to use real HTML tags – style indication is provided by the use of ASCII characters.

For instance, if you wanted to create a level 1 header (really big), simple prepend the line with ‘#’:

#My Really Big Headline

Markdown was created by John Gruber (of Daring Fireball fame): http://daringfireball.net/projects/markdown/syntax. I use to follow DaringFireball, but stopped when John started turning it into a forum for his political opinions.

Today I tripped on a really neat way to explore Markdown: http://www.markdowntutorial.com. The site presents info along with short lessons, and you must complete each one before the next one appears. Really cool use of HTML and I assume Javascript.

Github lets you embed images in our READMEs when you use Markdown, and thus you can possible users with screen shots of what your code does.

Also, I found a free text editor, LightPaper, that lets you write using Markdown in the left pane, and shows you the rendering in a right pane: http://clockworkengine.com/lightpaper-mac/. It doesn’t show images, but it’s really nice to see in real time what the README will look at in a web browser.