[Xcb] Let's hash this out

[Jeremy Kolb]

Okay... documentation generation.

Let's just hash it out on the list... because once we go with something
it will be harder to change later on and I'm itching to hack something
up and don't want to make any bad decisions that will be a pain to undo
later.  Since XCB is sort of a clean slate as far as documenting the X11
protocol we need to do this as best we can.

1. Doxygen:
We've already decided on doxygen... and I think that's a good choice
since we can make ps/pfd/latex/html/man.  Can we have different formats
for various output options?  So one for man pages and let's say another
format for pdf files?

2. XML markup:
At the very minimum we need to figure out the best way to describe a
request/reply in paragraph form and comment individual fields for
clarity and man pages.  For the later I'm thinking we could either have
a "brief" tag or attribute.  I'm leaning towards attribute but would a
tag be better? I don't really know how it would make a difference for
generation.  So we would have either:

<request name="MakeCurrent" opcode="5" brief="Makes a GLX context current.">
	<field type="glx:DRAWABLE" name="drawable" brief="The drawable
associated with the context." />
	<field type="glx:CONTEXT" name="context" brief="The context to make
current." />
	<field type="CONTEXT_TAG" name="old_context_tag" brief="the old context
tag" />
	<reply>
		<pad bytes="1" />
		<field type="CONTEXT_TAG" name="context_tag" brief="the context tag.
I don't remrember what this does."/>
		<pad bytes="20" />
	</reply>
</request>

Or

<request name="MakeCurrent" opcode="5" />
	<brief>Makes a GLX context current</brief>
	<field type="glx:DRAWABLE" name="drawable">
	  <brief>The drawable associated with the context."</brief>
	</field>
	<field type="glx:CONTEXT" name="context">
	  <brief>The context to make current.</brief>
	</field>
	<field type="CONTEXT_TAG" name="old_context_tag">
	  <brief>The old context tag"</brief>
	</field>
	<reply>
		<pad bytes="1" />
		<field type="CONTEXT_TAG" name="context_tag">
		  <brief>the context tag.  I don't remrember what this does</brief>
		</field>
		<pad bytes="20" />
	</reply>
</request>

The brief tag/attribute would also apply to everything else (errors,
fields, enums etc.)

For the "paragraph" description or what you find in the pdfs we'd
probably need a "description" tag of some sort.  Or we could use the
same tag for everything and use it differently depending on the context.
 I've also been thinking about error tags and I think we need something
like:

request...
<error name="blah" thrown-when="param size is larger than yo momma." />
or something like that.

3. Versioning.
We talked about this a long time ago and we're going to need to figure
this one out (especially with randr++ coming out soon).  Alp... what did
you encounter in your branch? Any ideas?

Okay, I'm done.  Discuss.

Jeremy