Cocoa API comments guideline

Question

I'm maintaining an utility cocoa-objc framework which keeps growing. Coming from Java, I'm used to write javadoc comments for all the API I write. What are the guidelines for writing good API comments in cocoa-objc ? Is there a tool to automatically generate an API documentation like Javadoc (what is the tool used by apple for generating their framework documentation ?)

Answer 1

There is an open source tool that Apple provides, although it's not nearly as ubiquitous for Objective-C as javadoc has become for Java. You can see the tool's homepage here. A lot of open source frameworks that I have seen use doxygen to generate their documentation, although I personally don't care for the documentation generated by doxygen at all. Apple's tool page (linked above) has links to download the utilities, links to the documentation and links to the source.

Answer 2

Use Doxygen and DoxyClean. Apple provides HeaderDoc, but DoxyClean's output is better in most ways.

You might also try DocXact. I've never used it, so I don't know how well it works or what its output (which it claims is “Apple Style”) looks like.