[Xcb] Some autogenerated docs questions...

[Ulrich Eckhardt]

Hi!

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.


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, but looking at c_client.py I find that not even that is the 
case! So, these are more or less noise in the generated files, not helping 
readability.


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.

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.


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.


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.



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

Cheers!

Uli
-------------- next part --------------
A non-text attachment was scrubbed...
Name: fix-xcb-autogen.0.patch
Type: text/x-patch
Size: 749 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20100622/f894face/attachment.bin>