[Xcb] api documentation with doxygen

[Vincent Torri]

On Wed, 15 Jun 2005, Jamey Sharp wrote:

> Hey Vincent,
>
> Your Doxygen patch looks fine to me. If you're waiting for my approval
> to start committing that sort of thing, you have it. :-)

ok, thank you :)

>
> I want to point out that the XCB protocol stubs can't be easily
> documented this way, though. I want to have protocol documentation start
> being folded into the XML descriptions, and then we'll be able to
> generate byproducts like Doxygen comments from there. (Not to mention
> reproducing something much like the usual protocol specifications.)

> Any comments on what documentation tags we might use, and where? I think
> re-using an existing XML documentation language would be a big feature.
> DocBook comes to mind, though if there's a standard XML form for Doxygen
> maybe that would be a good choice.

i think that it's not so hard to insert it in the XML description.

For example, for a function we need tags for
1) a brief description
2) a complete description
3) a description of each variables
4) a description of the returned value

after that, the xsl style sheet should easily create the doxygen
documentation in the header.

We also provide a gendoc script file, that is executed after the creation
of the headers, that launches doxygen, which creates the documentation
itself.

Vincent