Good code comments are an art form.
Even art needs structure, though, and I had hoped that HeaderDoc would provide me a ready-made structure for comments when they’re needed, with the promise of generating useful documentation later.
Testing the second part is what the rest of this post is about.
I downloaded HeaderDoc via its main page on Apple’s Web site, http://developer.apple.com/darwin/projects/headerdoc/, and tried to follow the instructions in the included README file to install it.
Problem: typing in the indicated
sudo make realinstall gives me an error. Well, OK, first it doesn’t work because I forgot my computer’s password. Tip: your install CD/DVD can reset your password. Extremely convenient. Second, it gives me an error because I don’t have
make installed. So I go to http://connect.apple.com, download Xcode 1.2, and install it. This also installs what I assumed was an older version of HeaderDoc, version 2.1. So the next time you’re trying to download all those segments of an Xcode install, blame a tiny smidgen of the bloat on HeaderDoc.
The real error is that there’s no file
xml2man in the folder called
xmlman/ inside the install package. There’s a makefile there, though, so I run it, run the command from above again, and it works. A post on the headerdoc-development mailing list describes this exact problem. How could a major release have been made without realizing this was a problem?
The package I downloaded is called, and all the documentation says, 8.0, but version of the
headerdoc2html utility installed by “8.0” is 2.1, just like the version I installed with Xcode 1.2. I must admit, version 8.0 of anything seems a bit dodgy these days. Things tend not to get up to that version number before being renamed, re-branded, etc.
There are more things that confuse me. The documentation states that comments can be embedded in “source code and header files.” I also remember reading a message on the headerdoc-development mailing list to the same effect, though I can’t find that message again now.
But the utility only seems to accept *.h files and directories, not *.m files. This certainly implies that comments in *.m files are ignored, and that’s been my impression from the tests I’ve run. This is a bit disappointing, since there are times when you want additional comments in the source code file, and I’d rather they weren’t lost.
Also, the documentation talks about “tagless syntax,” the ability to put a HeaderDoc tag in front of a function or method without needing to include a
@method tag in the comment. This would be good: computers don’t mistype, unlike humans. But I didn’t find this to work with comments for Objective-C methods. If I didn’t include the
@method tag, then the method didn’t show up in the documentation.
These sorts of issues give me the impression that if I use HeaderDoc syntax in my source code comments, it should be merely because I like the syntax, not because HeaderDoc at this point suits my documentation workflow.
I’d be curious to hear about other people’s experiences.