[Xcb] doxygen and documentation
vtorri at univ-evry.fr
Thu Oct 19 00:34:48 PDT 2006
Also, I've made for a lib a Makefile.am that compile and/or install the
documentation. You can find the code here:
if you think that it is worth, I can adapt it to xcb
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.
> This finally prompted me to run doxygen and put up the output at
> 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
>> 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?
More information about the Xcb