Re: [libvirt] [PATCH 2/4] Add usage type/id as a public API property of virSecret

On Fri, Sep 11, 2009 at 03:19:18PM +0100, Daniel P. Berrange wrote: > > +/** > + * virSecretGetUsageType: > + * @secret: a secret object > + * > + * Get the type of object which uses this secret > + * > + * Returns a positive integer identifying the type of object, > + * or -1 upon error. > + */ > +int > +virSecretGetUsageType(virSecretPtr secret) > +{ > + DEBUG("secret=%p", secret); > + > + virResetLastError(); > + > + if (!VIR_IS_SECRET(secret)) { > + virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__); > + return (-1); > + } > + return (secret->usageType); > +} > + > +/** > + * virSecretGetUsageID: > + * @secret: a secret object > + * > + * Get the unique identifier of the object with which this > + * secret is to be used > + * > + * Returns a string identifying the object using the secret, > + * or NULL upon error > + */ > +const char * > +virSecretGetUsageID(virSecretPtr secret) > +{ > + DEBUG("secret=%p", secret); > + > + virResetLastError(); > + > + if (!VIR_IS_SECRET(secret)) { > + virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__); > + return (NULL); > + } > + return (secret->usageID); > +} > + Looking from the outside I find that hard to graps especially the last one. virSecretGetUsageID return value supposed to be an UUID , the comment let the user expect this but it seems to be actually free form. I'm not against the patch but I think this needs some example or improved comments to really set properly the mechanism and expectations for the user. This may come after as a set of documentations, but if the function description could be clarified a bit this would be nice.