On Tue, Mar 27, 2012 at 04:59:48PM +0100, Matthew Booth wrote:
On 03/27/2012 04:20 PM, Richard W.M. Jones wrote:
>On Tue, Mar 27, 2012 at 04:00:57PM +0100, Matthew Booth wrote:
>>The generator doesn't make a very good job of guestfs-sections.txt. This
change
>>manually fixes its title, and moves various sections which shouldn't be in
the
>>documentation into a Private subsection.
>>
>>This change requires removing the --rebuild-sections command line option from
>>gtkdoc-scan. This means that any future apis will have to be manually added to
>>guestfs-sections.txt if they are to appear in the gtk-doc output.
>
>Sorry, but no. I took a strong stance against *any* manually hackery
>and over time that stance has proven to be a good one. Imagine we'd
>done this with other bindings -- that would by now have negated all
>the good work we did with the generator.
>
>Please explain why the generator cannot get this right, but a human can.
>Is there some missing information we need in the generator?
Firstly, 'generator' in this context is the gtk-doc generator, not
the libguestfs generator. The fundamental issue seems to be that it
doesn't correctly handle more than 1 class per source file. This
patch is, frankly, a fudge. However, it makes the output somewhat
bearable. The correct fix for this is to split guestfs-gobject.c
into multiple source files. This is certainly possible, but a load
of donkey work I wanted to leave for another day.
I don't think this is such a lot of work. Is it one per method, one
per class, (some other)?
Java requires separate files for each class, where libguestfs structs
are mapped to classes, thus each requires a separate file. It's not
onerous at all to generate these + the associate Makefile machinery:
https://github.com/libguestfs/libguestfs/blob/e8ef35df267de6fd6308d0c49a6...
https://github.com/libguestfs/libguestfs/blob/e8ef35df267de6fd6308d0c49a6...
The manual hackery required here is not onerous, and the build
system makes it extremely simple to both notice and fix. I deleted 3
entries from guestfs-sections.txt at random and ran make in
gobject/docs. The output was:
DOC Scanning header files
DOC Introspecting gobjects
DOC Rebuilding template files
./guestfs-unused.txt:1: warning: 3 unused declarations.They should
be added to guestfs-sections.txt in the appropriate place.
DOC Building XML
./guestfs-unused.txt:1: warning: 3 unused declarations.They should
be added to guestfs-sections.txt in the appropriate place.
DOC Building HTML
The contents of guestfs-unused.txt is:
guestfs_session_equal
guestfs_session_get_pid
guestfs_session_inotify_close
which are the 3 apis I deleted. All that's required to fix this is
to copy those 3 entries into the api list in guestfs-sections.txt.
So I agree it's not ideal, but its a not-too-onerous, pragmatic,
temporary workaround.
My argument is the same ... what if we'd done this for all the other
bindings? It would negate the benefit of the generator.
Rich.
--
Richard Jones, Virtualization Group, Red Hat
http://people.redhat.com/~rjones
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine. Supports Linux and Windows.
http://et.redhat.com/~rjones/virt-df/