[libvirt] [PATCH v2 3/5] domain: Document VIR_DOMAIN_XML_MIGRATABLE

[John Ferlan]

On 2/14/19 4:29 PM, Eric Blake wrote:
> Commit 28f8dfdc (1.0.0) added a flag to virDomainGetXMLDesc, but
> failed to document its effects.
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
>  src/libvirt-domain.c | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
> index 54ca18f249..6158382d07 100644
> --- a/src/libvirt-domain.c
> +++ b/src/libvirt-domain.c
> @@ -2559,7 +2559,13 @@ virDomainGetControlInfo(virDomainPtr domain,
>   * currently running domain.  If @flags contains
>   * VIR_DOMAIN_XML_UPDATE_CPU, then the portion of the domain XML
>   * describing CPU capabilities is modified to match actual
> - * capabilities of the host.
> + * capabilities of the host.  If @flags contains VIR_DOMAIN_XML_MIGRATABLE,
> + * the XML is altered to trim redundant information that might interfere
> + * with migration to an older version of libvirt, as well as expose additional
> + * information internal to libvirt; this flag is rejected on read-only
> + * connections, and the resulting XML might not validate against the schema,
> + * but it can serve as a starting point for custom XML in calls such as
> + * virDomainMigrate2().

You could just use the same attribution from the referenced commit
message, e.g. "virDomainMigrate{,ToURI}2 or virDomainSaveFlags."

I'm not insistent, just following back links. There could be other
examples by now too I suppose.

Reviewed-by: John Ferlan <jferlan at redhat.com>

John

>   *
>   * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
>   *         the caller must free() the returned value.
>