[Xcb] api documentation with doxygen

[Vincent Torri]

On Wed, 15 Jun 2005, Jeremy Kolb wrote:

> Quoting Vincent Torri <Vincent.Torri at iecn.u-nancy.fr>:
>
> > On Wed, 15 Jun 2005, Jamey Sharp wrote:
> >
> > > On Sat, 2005-05-21 at 09:33 +0200, Vincent Torri wrote:
> > > > Hello,
> > >
> > > Hi Vincent!
> > >
> > > > i've just made a first attempt of api documentation in xcb-util with
> > > > doxygen. I have documented only 2 functions. You can see the result
> > here:
> > > >
> > > > http://www.iecn.u-nancy.fr/~torri/files/xcb/doc/html/
> > > >
> > > > do you think it is worth continuing documenting xcb-util ?
> > > >
> > > > I have also xslt files that could give you gtk documentation style, if
> > you
> > > > don't like doxygen output (like me ;) )
> > >
> > > Documentation is a good thing, definitely. I'm glad somebody is thinking
> > > about it. :-)
> > >
> > > I don't have any particular preference for which tools or styles to use
> > > in the documentation, so I think it's pretty much up to whoever
> > > implements it. Which means I think you get to make it look however you
> > > want, Vincent. :-)
> > >
> > > I'd like to see what the changes to the code look like before we start
> > > adding documentation all over the place, though. It looks to me like you
> > > haven't committed your changes for the XCBImage documentation: would you
> > > post a patch to the mailing list so we can see what this stuff looks
> > > like?
> >
> > About the tool, doxygen is the mst used and the most advanced. About the
> > style, I use the xml output of doxygen, and I create a html file from it
> > with a stylesheet file.
> >
> > About the code, I prefer putting the documentation in the headers:
> > usually, when I look at an api, i look at the header. If in addition,
> > there is a documentation inside, it's better :) In addition, in the
> > header, there are all the api functions. So, if we document the header, we
> > should be abl to comment all the functions without ommiting one, and also
> > only which are necessary for the user
> >  Anyway, some documentation in the header is needed as we could document
> > the enums, structs, macros, etc...
> >
> > Vincent
>
>
> Docs would be very cool.  Should we do manpages too?

they could be automatically generated by doxygen :)

in fact, doxygen can export the doc into html, xml, latex, man pages.
Which should be sufficient, i think :)

Vincent