[Xcb] api documentation with doxygen

[Jamey Sharp]

On Wed, 2005-06-15 at 18:54 +0200, Vincent Torri wrote:
> On Wed, 15 Jun 2005, Jamey Sharp wrote:
> > 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

That sounds about right, except remember that XML-XCB doesn't describe
any functions: it describes X protocol. So the code generator will have
to automatically generate documentation for code it generates. The
return values of functions, for example, will all have to be fully
automatically documented. Not that this is a bad thing. :-)

If you go look at any protocol specification document, you'll see that
all it has is #2, the complete description. Conventionally these
documents have only explained the semantics of each field in the midst
of this complete description, so #3 is basically missing, and in those
documents there wasn't obviously any reason to include the brief
description, #1. And as I said, #4 is meaningless in that context.

As we start documenting this stuff, somebody's going to have to type
some new text that's not in any specification. :-(

By the way, I want to point out that I really don't want any
Doxygen-specific notation in the XML. That would make generating
JavaDocs or Literate Haskell or specification documents hard.

--Jamey