[rrd-developers] [rrd] Re: API doc

[Tobias Oetiker]

Today Sebastian Harl wrote:

> Hi Tobi,
>
> On Wed, Sep 03, 2008 at 09:25:10AM +0200, Tobias Oetiker wrote:
> > Today Sebastian Harl wrote:
> > > On Tue, Sep 02, 2008 at 11:34:37PM +0200, Tobias Oetiker wrote:
> > > > I think the key here is to document what happens, so if the library
> > > [...]
> > >
> > > Which reminds me that the librrd API has not been documented yet (or did
> > > I miss something?). Is anybody working on that already? Else, I will, at
> > > least, put it on my TODO list. If I come up with something incomplete,
> > > some more people might contribute to it ;-)
> >
> > nope, no documentation yet ... apropos, I would like to see this
> > done with doxygen, I will be glad to add your patches.
>
> Ugh, frankly, I hate doxygen. I would have done that using POD as well
> (just like all other documentation for rrdtool) and then generated
> manpages from that. If you insist on doxygen, somebody else will have to
> do that, I'm afraid. info-pages or asciidoc would be fine for me as
> well. Tons of different browsers are available for the former while POD
> and asciidoc allow for the creation of HTML pages (and quite a few other
> formats).

The reason I come up with doxygen is that I want to have the 'per
function' documentation integrated in the c code. Since this realy
helps with keeping things up todate. And from what I hear doxygen
is the tool of choice (I have not used it myself).

But if  you have deeper insights into this (embeding docs into c)
please let me know.

Also for other types of documentation aboout librrd (like how to
use it on a more general level) I am most happy with pod.

also if you would like to try embedding pod into c (which should
work as well) then this would be cool to, except that there we have
no support for describing parameter lists and such in a well
defined manner.

cheers
tobi


-- 
Tobi Oetiker, OETIKER+PARTNER AG, Aarweg 15 CH-4600 Olten, Switzerland
http://it.oetiker.ch tobi at oetiker.ch ++41 62 775 9902 / sb: -9900