[Xcb] api documentation with doxygen
jkolb at brandeis.edu
Wed Jun 15 11:34:56 PDT 2005
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
> > > 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
> > > 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
> > > 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.
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
More information about the xcb