Re: [Qemu-devel] [PATCH v6 5/5] doc: Introduce coding style for errors

[Markus Armbruster]

Lluís Vilanova <address@hidden> writes:

> Markus Armbruster writes:
>
>> Lluís Vilanova <address@hidden> writes:
>>> Markus Armbruster writes:
>>> 
>>>> Lluís Vilanova <address@hidden> writes:
>>>>> Gives some general guidelines for reporting errors in QEMU.
>>>>> 
>>>>> Signed-off-by: Lluís Vilanova <address@hidden>
>>>>> ---
>>>>> HACKING |   37 +++++++++++++++++++++++++++++++++++++
>>>>> 1 file changed, 37 insertions(+)
>>>>> 
>>>>> diff --git a/HACKING b/HACKING
>>>>> index 12fbc8a..b738bce 100644
>>>>> --- a/HACKING
>>>>> +++ b/HACKING
>> [...]
>>>>> +7.2. Errors in user inputs
>>>>> +
>>>>> +The 'loc_*()' functions in "include/qemu/error-report.h" will extend the
>>>>> +messages from 'error_report*()' with references to locations in inputs 
>>>>> provided
>>>>> +by the user (e.g., command line arguments or configuration files).
>>> 
>>>> This is probably too terse to help much on its own.  Perhaps
>>>> error-report.h should have usage information, like error.h.
>>> 
>>> I can try adding that, although I've barely used this part of the interface.
>
>> Documenting something you're not familiar with risks messy and laborious
>> review.  I'd simply drop this section for now.  If you have appetite for
>> more after you got the rest in, you can do another patch.
>
> Mmmm, I still think that a terse reference is better at directing developers 
> to
> the right header than just not commenting it. I think that this type of 
> patches
> are not funny to anyone, so this risks having no metion of loc_* in the 
> near/mid
> future.
>
> But hey, I might just be too pessimistic :)

If you want to cover error locations in HACKING briefly, that's okay
with me, but it needs to be correct.  I'll look over your proposed patch
again.