“In a world gone mad…one man”, a.k.a. Pesky Implementation Details

Have you seen the trailer for Jerry Seinfeld’s movie Comedian? It skewers the deep, ominous voiceovers of Hollywood blockbuster trailers by showing what seems like a real movie announcer in his recording booth.

But the person behind the scenes is no laughing matter (sorry!) for the purpose I talked about in my last post: finding a comments format that had a worthwhile translator into documentation.

I was planning on spending some time trying to track down the HeaderDoc implementors, to find out the status of the project and maybe some answers to the puzzles I’ve discovered, but Wolf’s comment about Doxygen got me thinking along different lines.

In general, I think a sense of ownership really matters, and it’s easier for one person, the initial author, to own a project. Doxygen is the project of “one man,” Dimitri van Heesch, and it does seem to have momentum and a much more active mailing list.

I’m still planning on finding out more about HeaderDoc, but I’ll probably try Doxygen first.

Can I just exchange one for another? Is it just an implementation detail? I’ve found that most implementations aren’t interchangeable, and any significant project design does require knowledge of how it’s going to be implemented, even if just the bare outlines, to succeed. This is why I’m chasing after implementation first.

Will it be enough, in a world gone mad, to keep me happy?

I’ll let you know.

2 comments

  1. Chris Reed

    You’ve probably already made a decision, but I’d really recommend that you use Doxygen. It’s got a much better parser–it actually understands the source code, so you don’t have to put @function @class etc everywhere. And btw, that’s the main thing that makes it difficult to transition between the two.

    Also, Doxygen produces much more flexible output, and can even generate RTF or XML (i.e., as XSLT input).

    Plus, Dmitri is really, really good about fixing bugs and releasing new versions. Over the past 3-4 months he’s added excellent ObjC support.