I'm a Mac developer with a very strong Java background. I've documented my sources using Javadoc, a lot.
Thank you all!
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.
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).
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.
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.
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.
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
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.