[Xcb] proposal for documenting the protocol description (part 1)

[Vincent Torri]

Hey,

Jeremy and I have discussed a bit about what and how we should add 
documentation in the protocol description.

if we use doxygen, a function needs a brief documentation, a detailed one 
and documentation for the arguments (and eventually the return value too)

here is a template:

   <request name="QueryVersion" opcode="0">
     <doc>
       <brief>******</brief>
       <detailed>*****</detailed>
     </doc>
     <reply>
       <field type="BOOL" name="shared_pixmaps" doc="***" />
       <field type="CARD16" name="major_version" doc="***" />
       <field type="CARD16" name="minor_version" doc="***" />
       <field type="CARD16" name="uid" doc="***" />
       <field type="CARD16" name="gid" doc="***" />
       <field type="CARD8" name="pixmap_format" doc="***" />
       <error code=10 name="BadAccess" when="***" />
     </reply>
   </request>

the error tag can be used for the server side. If several errors can 
occur, we add several error tags, of course.

I don't know if the doc tag should go into the reply tag in that case, or 
not.

What do you think ?

Vincent