[Xcb] api documentation with doxygen

[Jeremy Kolb]

Quoting Jamey Sharp <jamey at minilop.net>:

> 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
>

What's sad is that in some cases we'll be generating more complete
documentation than the descriptions already in xc (Xv comes to mind).

And there may even be less mistakes. :P

Jeremy