[Xcb] api documentation with doxygen

[Jeremy Kolb]

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?

Jeremy