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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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. :)

> >>    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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]