[libvirt] [PATCH] Docs: Improve documents for several APIs

Eric Blake eblake at redhat.com
Mon Jan 9 20:57:41 UTC 2012


On 01/09/2012 12:04 AM, Osier Yang wrote:
> virDomainGetBlockIoTune uses virTypedParameterFlags actually. And
> The definition of virTypedParameterFlags contains virDomainModificationImpact.

NACK. From libvirt.h.in:

typedef enum {
    VIR_DOMAIN_AFFECT_CURRENT = 0,      /* Affect current domain state.  */
    VIR_DOMAIN_AFFECT_LIVE    = 1 << 0, /* Affect running domain state.  */
    VIR_DOMAIN_AFFECT_CONFIG  = 1 << 1, /* Affect persistent domain
state.  */
    /* 1 << 2 is reserved for virTypedParameterFlags */
} virDomainModificationImpact;

typedef enum {
    /* 1 << 0 is reserved for virDomainModificationImpact */
    /* 1 << 1 is reserved for virDomainModificationImpact */
    VIR_TYPED_PARAM_STRING_OKAY = 1 << 2,
} virTypedParameterFlags;

Neither enum contains the other (rather, both enums merely ensure that
they reserve values so as not to overlap), and I think listing both
enums is appropriate for the documentation.

> @@ -7149,7 +7149,7 @@ error:
>   * @params: pointer to interface parameter objects
>   *          (return value, allocated by the caller)
>   * @nparams: pointer to number of interface parameter; input and output
> - * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
> + * @flags: bitwise-OR of virTypedParameterFlags

I think hunks like this actually lose information,

>   *
>   * Get all interface parameters. On input, @nparams gives the size of
>   * the @params array; on output, @nparams gives how many slots were
> @@ -17790,7 +17790,7 @@ error:
>   * @params: Pointer to blkio parameter object
>   *          (return value, allocated by the caller)
>   * @nparams: Pointer to number of blkio parameters
> - * @flags: An OR'ed set of virDomainModificationImpact
> + * @flags: bitwise-OR of virTypedParameterFlags

and while I agree that this hunk is trying to improve things, it didn't
go all the way in making the improvement.

I'll send a v2 counter-proposal shortly.

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120109/8ffe8445/attachment-0001.sig>


More information about the libvir-list mailing list