[Xcb] doxygen and documentation

[Vincent Torri]

Hey,

I would like to mention that I have sent a mail about a possible add of a 
doc rule in the Makefiles. Without answer.

If the idea is good enough, i'll go on writing a patch

if you don't want it, i'll not spend time on it

but give me an answer, please.

Vincent

On Thu, 19 Oct 2006, 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.
>
> 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.
>
>> 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.
>
>> 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?
>
> --Jamey
>