[Xcb] Some autogenerated docs questions...

[Jamey Sharp]

Hello!

On Tue, Jun 22, 2010 at 2:33 PM, Ulrich Eckhardt <doomster at knuut.de> wrote:
> I stumbled across a few things concerning the documentation in autogenerated
> header files. Obviously (since I opened my mouth...) I volunteer to patch this
> in case there is a consensus on taking actions.

The header documentation has never been completed, and patches are
very welcome. :-)

We've always intended to add more annotations to the XML containing
documentation about the protocol. Ideally, we'd be able to replace the
manually written documents on the core protocol and extensions with
documentation auto-generated from the XML. Those same annotations
would hopefully be copied into XCB's generated headers. There's a lot
of good text already written about the X protocol, just waiting for
somebody to do something useful with it.

I don't think you'll get much debate about your proposals. Make things
better and we'll all be happy.

> First things, all the "/**< */". I first thought that they were placeholders
> for places where an optional comment could be but wasn't specified in the
> source XML files, ...

This is true, but nobody ever picked a tag to represent such comments,
so of course there's nothing for the code generator to read.

> Second thing, there are function declarations that look like this:
>
>   /**
>    *  .... (possibly hand-written docs)
>    */
>
>   /************
>    ** generated repetition of parameters
>    ************/
>
>   return_t function(parameters);
>
> What I don't get here is why the function parameters are repeated there. IMHO
> this doesn't add any information that isn't readily available a few lines
> below.

Or a few lines above. This is supposed to be Doxygen input; at least
one of those comment blocks is probably wrong.

> Further, this means that there are suddenly two "headers" for one function,
> with one even visually separating one from the function it describes. This
> isn't helped by the fact that there is one empty line in between those and the
> preceding/following function. I'd use an asterisk line or two blank ones to
> separate two functions, or maybe not use any blank lines between the comment
> and the prototype.

I think I'd prefer the last option, but again, any improvements are welcome.

> Third thing is the include guards. These are currently like "__RES_H". In this
> case, the name is unfortunately generic. Further, any macro or identifier
> containing two consecutive underscores is reserved to the compiler. I'd use
> something starting with XCB, like XCB_<name>_HEADER_INCLUDE_GUARD. This is
> long enough to make any collisions very unlikely and more portable.

We discussed this recently on the list, and consensus was that yeah,
somebody should fix that. Perhaps that somebody is you?

> Fourth thing is that some comments are closed with "**/" and some use "*/"
> instead. The very first one even uses "/*" to open a comment. I'm impartial on
> either variant, but I'd prefer it to be consistent.

I assume Doxygen requires "/**" to open a comment, and I think I'd
prefer "*/" to close.

> Attached is a patchlet that marks one issue (where I'm not sure how to
> complete a sentence) and fixes another (where a period slipped in, chopping
> one sentence in half).

The fix looks good. Perhaps the wiki documentation will help you come
up with better text for the other part?

http://xcb.freedesktop.org/ProtocolStubApi/#index4h2

Thanks for working on XCB's documentation. That's always welcome!

Jamey