Re: Using doxygen (or something similar) to generate API docs [was [PATCH 4/4] Add a function string_list_longest_prefix()]

From: Jeff King <peff@peff.net>
Date: Sep 10, 2012, 21:56 UTC
Message-ID: <20120910215633.GB1537@sigill.intra.peff.net>
In-Reply-To: <504E3DA8.7040906@alum.mit.edu>

On Mon, Sep 10, 2012 at 09:21:12PM +0200, Michael Haggerty wrote:

> I'm renaming this thread so that the bikeshedding can get over ASAP.

Thanks. :)

Show 10 quoted lines

> >>    http://tomdoc.org/
> >>
> >> Looks much nicer to me than most doxygen I've seen. But again, it's been
> >> a while, so maybe doxygen is nicer than I remember.
> 
> I don't have a personal preference for what system is used.  I mentioned
> doxygen only because it seems to be a well-known example.
> 
> From a glance at the URL you mentioned, it looks like TomDoc is only
> applicable to Ruby code.

Yeah, sorry, I should have been more clear; tomdoc is not an option because it doesn't do C. But what I like about it is the more natural markup syntax. I was wondering if there were other similar solutions. Looks like "NaturalDocs" is one:

  http://www.naturaldocs.org/documenting.html

On the other hand, doxygen is well-known among open source folks, which counts for something. And from what I've read, recent versions support Markdown, but I'm not sure of the details. So maybe it is a lot better than I remember.

> > Doxygen has a the very nifty feature of being able to generate
> > callgraphs though. We use it extensively at $dayjob, so if you need a
> > hand building something sensible out of git's headers, I'd be happy
> > to help.

It has been over a decade since I seriously used doxygen for anything, and then it was a medium-sized project. So take my opinion with a grain of salt. But I remember the callgraph feature being one of those things that _sounded_ really cool, but in practice was not all that useful.

> My plate is full.  If you are able to work on this, it would be awesome.
>  As far as I'm concerned, you are the new literate documentation czar :-)

Lucky me? :)

I think I'll leave it for the moment, and next time I start to add some api-level documentation I'll take a look at doxygen-ating them and see how I like it. And I'd invite anyone else to do the same (in doxygen, or whatever system you like -- the best way to evaluate a tool like this is to see how your real work would look).

-Peff