views:

4193

answers:

8

I'm a Mac developer with a very strong Java background. I've documented my sources using Javadoc, a lot.

  • What's the way to go with Cocoa and Xcode?
  • Are there any documentation tools supplied together with Apple's Developer Tools?
  • Is Doxygen the way to go? What are the alternatives?

Thank you all!

+1  A: 

I'm not aware of any Xcode-supported doc tool, and I don't recall seeing any documentation markup in any Apple sample-code.

Personally I use Doxygen, which suits my needs just fine.

+12  A: 

Doxygen works with Objective-C (and hence on Cocoa code), Apple also provides the headerdoc documentation generator tool. Then there's GNUstep's autogsdoc, too.

Graham Lee
Personally, I wouldn't recommend anything but Doxygen (including HeaderDoc, which is a mish-mash of hard-to-configure Perl scripts) as "the way to go with Cocoa and Xcode". It's good to have alternatives, but in this case they're really not very satisfactory. I do wish there was a tool dedicated to Objective-C documentation that could create documentation that looks exactly the way I want, and Doxygen still has a number of issues with Objective-C protocols. Someday...
Quinn Taylor
Yeah, I happen to use doxygen myself. In all honesty I very rarely generate the fair copy though, I just read it in-line.
Graham Lee
+9  A: 

I use Doxygen and Doxyclean to generate cleaner, more Apple-like documentation that what Doxygen natively produces.

(It should be said that Doxyclean doesn't reformat all Doxygen output - you're definitely getting a subset of the documentation you'd get straight from Doxygen).

Jablair
+4  A: 

Forget headerdoc. Headerdoc is a pile of /** poo */. Stick with doxygen. It works just fine and produces good documentation. It can understand (or at least not blow up on) the more unique Objc constructs (protocols, categories etc). Doxygen style doc markup is really a superset (with the right configuration) of headerdoc anyway.

schwa
+8  A: 

If you're using Xcode ≥ 3.0, you probably want to check out Doxygen, as others have suggested, and then read this article on Apple's Developer site for creating Xcode documentation sets for your project (viewable in Xcode's help system) using Doxygen.

Barry Wark
+1  A: 

The other thing to remember about Doxygen is that it does a great job of C++ and so if your Objective-C code base includes a common C++ engine, will have both in the same documentation base.

Andy Dent
HeaderDoc supports C++, and a number of other languages as well.
AlBlue
+3  A: 

I have a similar background in Java, and had the same question when I learned Objective-C and Cocoa. Currently, there's no tool that's perfectly tailored for Objective-C, but Doxygen is the best option by far right now. (I agree that HeaderDoc is overly complex, especially for small projects, and every other tool I've found is dead or abandonware, including AutoDoc and ObjcDoc.) The developer of Doxygen has improved Obj-C support consistently over the past few releases, including several bugs I've submitted where protocols weren't handled correctly.

Within Xcode, I create a Documentation target with a single Run Script phase which invokes Doxygen using a doxyfile saved in the project directory. It helps to create a symlink to the Doxygen executable in /usr/local/bin so you don't have machine-specific paths in a shared doxyfile.

Doxygen supports virtually all the comment tags you'd expect to see in Javadoc, plus a lot more. I've used it extensively on an open-source framework I develop — the resulting documentation is auto-generated using a Subversion post-commit hook and available online:

http://dysart.cs.byu.edu/CHDataStructures/

Notice the diagrams which document inheritance and collaboration. These can optionally be generated using the dot tool, available with GraphViz, either v1.13 or v2.20. The diagrams are clickable HTML image maps, which helps make up for the lack of information at the top which you'd expect in Javadoc (such as inheritance hierarchy) or Apple's Cocoa documentation (such as adopted protocols).


As an aside, since CHDataStructures is a framework with lots of public APIs, I write lots of comments — approximately 70% of my header files. Since the documentation is more useful in the form generated by Doxygen, I opt to strip out most comments from the Release version of the headers, which dramatically reduces the on-disk size for the headers. I've posted the full explanation and code on the BYU CocoaHeads wiki:

http://cocoaheads.byu.edu/wiki/stripping-comments-source-code

Quinn Taylor
One of the strengths of Doxygen is the ability to put documentation in other files, it doesn't need to clutter up your headers. I have used this approach to add docs to _frozen_ code.
Andy Dent
Very true, that's a very cool aspect of Doxygen. I don't use it personally since I'm documenting my own source, but having the option to do that is extremely nice.
Quinn Taylor
+1 Great answer, thanks!
Perspx
+2  A: 

I feel none of them is good enough and docs generated by them are not up to Apple standard. So I've reported a bug to Apple to request a native documentation generation tool in Xcode, please vote for it if you also want such a tool.

an0
stigi