[Xcb] doxygen and documentation

[Jeremy Kolb]

Jamey Sharp wrote:
> On Wed, Oct 18, 2006 at 09:40:08PM -0400, Jeremy Kolb wrote:
>> So I know nothing of xslt or doxygen but I hacked up this diff to
>> generate doxygen comments for the proto headers.  Most of it is stub
>> work and shows us where we need to go from here but the resulting html
>> pages are pretty cool.
> 
> Great! This is exactly what I wanted for a first step in this direction.
> Thanks!
> 
> This finally prompted me to run doxygen and put up the output at
> 	http://xcb.freedesktop.org/manual/
> which should replace our XcbApi pages. If somebody gets around to fixing
> the wiki before I do I sure won't complain. :-) Checking that everything
> on the wiki is also in the Doxygen comments is a necessary first step...
> 
>> My xslt sucks and the patch needs to be cleaned up a lot, it's just a
>> proof of concept hack.
> 
> I thought about applying it anyway, but I'd like Josh to review first. I
> bet he can make it a lot easier to describe these generated comments.
> 

That would be really good.  If we could modularize it some how then all
the better.

> However, I generated the above page using the patched c-client.
> 
>> 1.  We need some type of <brief> or <description> field that we can tie
>> in to items/fields/requests/constants/etc., to give a basic description
>> of an item.
> 
> An old goal that I still hope for here is to be able to take the full
> text from the original protocol specifications and incorporate it into
> the XML descriptions. That text then can be copied into the Doxygen
> comments, as well as being used to regenerate pure protocol
> documentation. If that has to be split into a "brief" and "full"
> description, I guess that's OK, but I'm inclined to turn on Doxygen's
> JAVADOC_AUTOBRIEF mode and get rid of all the explicit "@brief" tags.
> 

JAVADOC_AUTOBRIEF creates the brief for you?  I think it's best to have
both.  A brief for things like fields etc. and fully describe them, and
a full for the giant block of text.

>> 2.  Maybe a <throws> or similar tag... something like <throws
>> name="BadMatch" when="index is out of range" />  so we can document
>> which requests throw what errors (and events?).
> 
> I think that'd be great. Even better if we can devise a description that
> allows some simple test cases or server-side checks to be
> auto-generated.
> 
That would be pretty cool.  I hadn't thought of that.

>> 3.  I think it would be worth while to make enums field types and then
>> when generating c code replace the field type with uint32_t or whatever.
>> That would be really good for documentation and higher level bindings.
> 
> Yes, please. :-) I think it's not even an ABI change, though that's
> worth checking. Propose a patch?

I'll look into it.

> 
> --Jamey
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb