documentation effort (was doc: Add auto-generated Wayland Library chapter)

[Tiago Vignatti]

Hi all,

On 10/12/2012 03:26 PM, Tiago Vignatti wrote:
> On 10/12/2012 12:57 AM, David Herrmann wrote:
>>
>> I will be looking into writing the XSL files to generate the
>> man-pages. However, it's a mess installing publican here so I will
>> probably not work on the publican XSL files.
>
> great! Seems that now Ander is working on the top of this patchset also
> and adding doxygen style information on libwayland headers. So the tree
> with this work is here:
>
> http://cgit.freedesktop.org/~vignatti/wayland/log/?h=doc

I updated the tree, pulled Ander's patches and rebased it on top of 
krh/next.


Doxygen is extracting now the pretty commentaries from the code and 
outputting onto the xml; we're not using them so far though. So we'd 
need to create a XSLT to fetch the information from the 
wayland-client_8c.xml, check function by function whether the static 
documentation (wl_display_connect.xml, etc) exists already and drop the 
desired output, being it the man-page or the publican. Actually we might 
probably want two XSLT stylesheets to ease the process then.

One thing that came up is where to insert the doxygen comments. Only on 
the .c, only on .h or on both? For instance, for non-generated 
functions, xcb has commentaries only on its .h. But doing this, one 
problem is that the programmer might forget to update the header while 
developing the implementation. For now, we started to drop commentaries 
only at wayland-client.c. Is it reasonable?


Thank you,

   Tiago