[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 05/23] error: Improve documentation around er
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v2 05/23] error: Improve documentation around error_append_hint() |
Date: |
Thu, 17 Dec 2015 20:00:17 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Eric Blake <address@hidden> writes:
> On 12/17/2015 11:04 AM, Markus Armbruster wrote:
>
>>>> + * Create an error and add additional explanation:
>>>> + * error_setg(&err, "invalid quark");
>>>> + * error_append_hint(&err, "Valid quarks are up, down, strange, "
>>>> + * "charm, top, bottom\n");
>>>
>>> Do we want to allow/encourage a trailing dot in the hint? I'm fine if
>>> we don't - but once we document its usage, we should probably then be
>>> consistent with what we document; qemu-option.c used a trailing dot,
>>> qdev-monitor.c did not.
>>
>> I'll fix this example.
>>
>>>> + *
>>>> + * Do *not* contract this to
>>>> + * error_setg(&err, "invalid quark\n"
>>>> + * "Valid quarks are up, down, strange, charm, top, bottom");
>
> Of course, if you put a trailing dot above, you'd also want it here in
> the 'don't contract' section.
Yes.
>>>> @@ -128,6 +138,7 @@ ErrorClass error_get_class(const Error *err);
>>>> * If @errp is anything else, address@hidden must be NULL.
>>>> * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its
>>>> * human-readable error message is made from printf-style @fmt, ...
>>>> + * The resulting message should not contain newlines.
>>>
>>> Should we also discourage trailing punctuation?
>>
>> Yes. How to best phrase it?
>
> Maybe:
>
> The resulting message should be a single phrase, with no newline or
> trailing punctuation.
What about ending the message with an exclamation mark?
>>> Should we also mention no need for leading 'error: ' prefix?
>>
>> Unlike the other anti-patterns, this one doesn't seem frequent in new
>> code.
>
> Fair enough.
>
>
>>>> /**
>>>> * Append a printf-style human-readable explanation to an existing error.
>>>> - * May be called multiple times, and safe if @errp is NULL.
>>>> + * @errp may be NULL, but neither &error_fatal nor &error_abort.
>>>
>>> As a native speaker, 'not' sounds better than 'neither' in that
>>> sentence. But I think both choices are grammatically correct.
>>
>> You mean "not &error_abort or &error_abort"?
>
> Yes, that works:
>
> @errp may be NULL, but not &error_fatal or &error_abort.
- Re: [Qemu-devel] [PATCH v2 02/23] error: Use error_report_err() where appropriate (again), (continued)
[Qemu-devel] [PATCH v2 07/23] qemu-nbd: Clean up "Failed to load snapshot" error message, Markus Armbruster, 2015/12/17
[Qemu-devel] [PATCH v2 12/23] error: Use error_prepend() where it makes obvious sense, Markus Armbruster, 2015/12/17
[Qemu-devel] [PATCH v2 11/23] error: Use error_reportf_err() where it makes obvious sense, Markus Armbruster, 2015/12/17
[Qemu-devel] [PATCH v2 20/23] vhdx: Fix "log that needs to be replayed" error message, Markus Armbruster, 2015/12/17