[libvirt] [PATCH] doc: Correct the default werror policy

[Osier Yang]

On 10/27/2011 01:08 AM, Laine Stump wrote:
> On 10/24/2011 07:46 AM, Osier Yang wrote:
>> <quote>
>> @item werror=@var{action},rerror=@var{action}
>> Specify which @var{action} to take on write and read errors. Valid 
>> actions are:
>> "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
>> "report" (report the error to the guest), "enospc" (pause QEMU only 
>> if the
>> host disk is full; report the error to the guest otherwise).
>> The default setting is @option{werror=enospc} and 
>> @option{rerror=report}.
>> @item readonly
>> </quote>
>>
>> libvirt doesn't set any default value for "(r)error_policy", the
>> original doc should mean QEMU sets "report" as the default value
>> for "werror", but it's not true, QEMU uses "enospc" as the default.
>> And it's better to document "(r)error_policy" are only supported
>> by QEMU.
>> ---
>>   docs/formatdomain.html.in |   20 +++++++++-----------
>>   1 files changed, 9 insertions(+), 11 deletions(-)
>>
>> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
>> index dc6b152..e98e709 100644
>> --- a/docs/formatdomain.html.in
>> +++ b/docs/formatdomain.html.in
>> @@ -1011,19 +1011,17 @@
>>               The optional<code>error_policy</code>  attribute controls
>>               how the hypervisor will behave on a disk read or write
>>               error, possible values are "stop", "report", "ignore", and
>> -            "enospace".<span class="since">Since 0.8.0, "report" since
>> -            0.9.7</span>  The default setting of error_policy is 
>> "report".
>> -            There is also an
>> -            optional<code>rerror_policy</code>  that controls behavior
>> -            for read errors only.<span class="since">Since
>> -            0.9.7</span>. If no rerror_policy is given, error_policy
>> -            is used for both read and write errors. If rerror_policy
>> -            is given, it overrides the<code>error_policy</code>  for
>> -            read errors. Also note that "enospace" is not a valid
>
>> +            "enospace".<span class="since">Since 0.8.0 (QEMU and KVM 
>> only),
>> +            "report" since 0.9.7</span>. QEMU sets error_policy as 
>> "enospc"
>> +            by default.
>
> This is definitely more correct than what's already there. My only 
> issue is that the description mixes libvirt's name of the attribute 
> "error_policy" with QEMU's value "enospc". Maybe instead it can just 
> say that QEMU defaults to "werror=enospc,rerror=report" when neither 
> error_policy nor rerror_policy are specified.

Oh, you are right, it shouldn't mix them together.

"rerror" is clarified later, so  how about following (with your
next suggestion) ?

if no "error_policy" is given, the write error policy will be left at
QEMU's default setting, which is "enospc".

>
>>   There is also an optional<code>rerror_policy</code>
>> +            that controls behavior for read errors only.<span 
>> class="since">
>> +            Since 0.9.7 (QEMU and KVM only)</span>. If no 
>> rerror_policy is
>> +            given, error_policy is used for both read and write 
>> errors. If
>> +            rerror_policy is given, it overrides 
>> the<code>error_policy</code>
>> +            for read errors. Also note that "enospace" is not a valid
>>               policy for read errors, so if<code>error_policy</code>  is
>>               set to "enospace" and no<code>rerror_policy</code>  is
>> -            given, the read error policy will be left at its default,
>> -            which is "report".
>> +            given, QEMU will set the read error policy as "report" 
>> by default.
>
> Maybe instead say '...the read error policy will be left at QEMU's 
> default setting, which is "report"'

This is better, :)

>
>
>> </li>
>> <li>
>>               The optional<code>io</code>  attribute controls specific
>
> Other than that, ACK.
>
> -- 
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list