[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [Libguestfs] [PATCH 15/16] gobject: Improve the structure of guestfs-sections.txt

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:


> 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.


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.

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]