[libvirt] [PATCH v2 1/4] Introduce virDomainFSTrim() public API

[Michal Privoznik]

On 29.11.2012 00:41, Eric Blake wrote:
>> This will call FITRIM within guest. The API has 4 arguments,
>> however, only 2 will be used for now (@dom and @minumum).
>> The rest two are there if in future qemu guest agent learns them.
> 
> s/in future/in the future/
> 
> 
>> +/**
>> + * virDomainFSTrim:
>> + * @dom: a domain object
>> + * @mountPoint: which mount point trim
> 
> s/trim/to trim/
> 
>> + * @minimum: Minimum contiguous free range to discard in bytes
>> + * @flags: extra flags, not used yet, so callers should always pass
>> 0
>> + *
>> + * Calls FITRIM within the guest (hence guest agent may be
>> + * required depending on hypervisor used). Either call it on each
>> + * mounted filesystem (@mountPoint is NULL) or just on specified
>> + * @mountPoint. @minimum tell that free ranges smaller than this
> 
> s/tell/hints/
> 
>> + * may be ignored (this is a hint and the guest may not respect
>> + * it).  By increasing this value, the fstrim operation will
>> + * complete more quickly for filesystems with badly fragmented
>> + * free space, although not all blocks will be discarded.
> 
> Maybe mention that the command may fail if @minimum is not 0.
> 

Right. But since I've already pushed the patches I am pushing a separate
commit to fix those nits under trivial rule:

commit 5049b53689128701e5bb72fa578467ac34071be9
Author:     Michal Privoznik <mprivozn at redhat.com>
AuthorDate: Thu Nov 29 09:30:58 2012 +0100
Commit:     Michal Privoznik <mprivozn at redhat.com>
CommitDate: Thu Nov 29 09:30:58 2012 +0100

    libvirt.c: Fix wording and grammar in virDomainFSTrim

    The documentation to this API has some defects from
    grammar and wording POV. These were raised after I've
    pushed the patches, so they are in a separate commit.

diff --git a/src/libvirt.c b/src/libvirt.c
index b1854e3..4581394 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -20229,18 +20229,19 @@ error:
 /**
  * virDomainFSTrim:
  * @dom: a domain object
- * @mountPoint: which mount point trim
+ * @mountPoint: which mount point to trim
  * @minimum: Minimum contiguous free range to discard in bytes
  * @flags: extra flags, not used yet, so callers should always pass 0
  *
  * Calls FITRIM within the guest (hence guest agent may be
  * required depending on hypervisor used). Either call it on each
  * mounted filesystem (@mountPoint is NULL) or just on specified
- * @mountPoint. @minimum tell that free ranges smaller than this
+ * @mountPoint. @minimum hints that free ranges smaller than this
  * may be ignored (this is a hint and the guest may not respect
  * it).  By increasing this value, the fstrim operation will
  * complete more quickly for filesystems with badly fragmented
  * free space, although not all blocks will be discarded.
+ * If @minimum is not zero, the command may fail.
  *
  * Returns 0 on success, -1 otherwise.
  */