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

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.

Matt
--
Matthew Booth, RHCA, RHCSS
Red Hat Engineering, Virtualisation Team

GPG ID:  D33C3490
GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490


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