[libvirt] Re: [PATCH] Fix API doc extractor to stop munging comment formatting

[Daniel P. Berrange]

On Fri, Sep 25, 2009 at 01:28:51PM +0100, Daniel P. Berrange wrote:
> The python method help docs are copied across from the C
> funtion comments, but in the process all line breaks and
> indentation was being lost. This made the resulting text
> and code examples completely unreadable. Both the API
> doc extractor and the python generator were destroying
> whitespace & this fixes them to preserve it exactly.

I meant to include an example of the difference when I sent this.

eg, launch python, type  'import libvirt' and then 'help(libvirt)'.

For the 'migrate' API currently you see

     |  migrate(self, domain, flags, dname, uri, bandwidth)
     |      Migrate the domain object from its current host to the
     |      destination host given by dconn (a connection to the
     |      destination host).  Flags may be one of more of the
     |      following: VIR_MIGRATE_LIVE   Attempt a live migration.  If
     |      a hypervisor supports renaming domains during migration,
     |      then you may set the dname parameter to the new name
     |      (otherwise it keeps the same name).  If this is not
     |      supported by the hypervisor, dname must be None or else you
     |      will get an error.  Since typically the two hypervisors
     |      connect directly to each other in order to perform the
     |      migration, you may need to specify a path from the source
     |      to the destination.  This is the purpose of the uri
     |      parameter.  If uri is None, then libvirt will try to find
     |      the best method.  Uri may specify the hostname or IP
     |      address of the destination host as seen from the source. 
     |      Or uri may be a URI giving transport, hostname, user, port,
     |      etc. in the usual form.  Refer to driver documentation for
     |      the particular URIs supported.  The maximum bandwidth (in
     |      Mbps) that will be used to do migration can be specified
     |      with the bandwidth parameter.  If set to 0, libvirt will
     |      choose a suitable default.  Some hypervisors do not support
     |      this feature and will return an error if bandwidth is not
     |      0.  To see which features are supported by the current
     |      hypervisor, see virConnectGetCapabilities,
     |      /capabilities/host/migration_features.  There are many
     |      limitations on migration imposed by the underlying
     |      technology - for example it may not be possible to migrate
     |      between different processors even with the same
     |       architecture, or between different types of hypervisor.


After my patch you get

     |  migrate(self, domain, flags, dname, uri, bandwidth)
     |      Migrate the domain object from its current host to the destination
     |      host given by dconn (a connection to the destination host).
     |      
     |      Flags may be one of more of the following:
     |        VIR_MIGRATE_LIVE   Attempt a live migration.
     |      
     |      If a hypervisor supports renaming domains during migration,
     |      then you may set the dname parameter to the new name (otherwise
     |      it keeps the same name).  If this is not supported by the
     |      hypervisor, dname must be None or else you will get an error.
     |      
     |      Since typically the two hypervisors connect directly to each
     |      other in order to perform the migration, you may need to specify
     |      a path from the source to the destination.  This is the purpose
     |      of the uri parameter.  If uri is None, then libvirt will try to
     |      find the best method.  Uri may specify the hostname or IP address
     |      of the destination host as seen from the source.  Or uri may be
     |      a URI giving transport, hostname, user, port, etc. in the usual
     |      form.  Refer to driver documentation for the particular URIs
     |      supported.
     |      
     |      The maximum bandwidth (in Mbps) that will be used to do migration
     |      can be specified with the bandwidth parameter.  If set to 0,
     |      libvirt will choose a suitable default.  Some hypervisors do
     |      not support this feature and will return an error if bandwidth
     |      is not 0.
     |      
     |      To see which features are supported by the current hypervisor,
     |      see virConnectGetCapabilities, /capabilities/host/migration_features.
     |      
     |      There are many limitations on migration imposed by the underlying
     |      technology - for example it may not be possible to migrate between
     |      different processors even with the same architecture, or between
     |      different types of hypervisor.


Regards,
Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|