[Xcb] XCB documentation effort

[Michael Stapelberg]

Hi,

Excerpts from Jamey Sharp's message of 2011-11-22 01:44:20 +0000:
> > At the moment, the action items are on my side. I will keep you (all) updated
> > in case I need anything :). Probably reviewing documentation on a regular basis
> > would be a good idea. We’ll see once some work is actually done.
> 
> Let us know!
OK, I started work on this. I modified xproto.xml to contain a new tag (<doc>),
for the MapWindow request only at the moment. This section then has a
<description> text which uses CDATA to get documentation in there easily. I
then modified xcbgen/xtypes.py to contain a Doc type and modified c_client.py
to check for the doc property and inject the appropriate comments into the
generated header file (xproto.h in this case).

Then I modified doc/xcb.doxygen.in and let doxygen run. It does generate
manpages, but only for types and modules. A module in the XCB case is something
like "xproto" (called man/man3/XCB__API.3 at the moment), which contains all
the structs, typedefs, functions, accessors, etc. As you can imagine, this is
unpractical to work with. One manpage per function (like xcb_map_window(3)) is
what I was going for.

Apparently, the best way to fix this is to actually group (\defgroup, \ingroup,
…) the functions manually (in our case: auto-generated by c_client.py). This
"works" in that it creates man/man3/xcb_map_window.3, in which we can put
xcb_map_window and xcb_map_window_checked. I’ve attached the resulting manpage
(with some dummy text, not real documentation) so that you can have a look.

The following things bother me with this manpage:
1) The title is screwed up since the \brief description (which is what ends up
   in the title) contains a new paragraph and thus will be in a separate line
   in the manpage. One doesn’t notice this in the HTML output. Any ideas on how
   to fix this?

2) For some reason, the type and variable name are not correctly separated in
   the "Function Documentation" section: "xcb_window_twindow)" instead of
   "xcb_window_t window)".

3) The "References …" line is totally unnecessary and not helpful for manpages.
   The manpage related configuration in Doxygen is very small and there seems
   to be no way to disable the references-line only for manpages. I guess we’d
   need a separate .doxygen file? Another argument for a separate .doxygen file
   is that the groups which have to be used to get manpages for every function
   clutter up the HTML documentation, because they end up in the "Modules"
   overview as subsections, while the functions themselves are no longer in the
   module page (but only in the subsection).

4) The "see also" section is "un-man-ish" in that it ends up in the "Detailed
   description" section instead of in its own proper section in the manpage.
   :-/

Your thoughts?

General questions:
1) I’m not sure if we should document types like xcb_map_window_request_t. Is
   that considered part of our public API? If so, what are the benefits vs.
   leaving that an implementation detail? I do understand the need to have
   events and replies exposed, but request structs? If this is intended, should
   we document them?

2) Is the modification of xproto.xml OK with you? I decided to go for a <doc>
   tag because it can then have sections for the individual fields and errors
   and whatever else we will stumble upon. I used the <description> tag to be
   able to use CDATA, which does not seem to be possible with XML attributes.
   Patches are attached.

Best regards,
Michael
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xproto-doc.patch
Type: application/octet-stream
Size: 1570 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111122/264b3def/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb-docs.patch
Type: application/octet-stream
Size: 1071 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111122/264b3def/attachment-0001.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_map_window.3
Type: application/octet-stream
Size: 1656 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111122/264b3def/attachment-0002.obj>