Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors

[Markus Armbruster <armbru@redhat.com>]

"Daniel P. Berrange" <berrange@redhat.com> writes:

> On Mon, Nov 23, 2015 at 09:05:30PM +0100, Lluís Vilanova wrote:
>> Daniel P Berrange writes:
>> [...]
>> > I don't think this "Errors in user inputs" vs "Other errors" distinction
>> > really makes sense. Whether an error raised in a piece of code is related
>> > to user input or not is almost impossible to determine in practice. So as
>> > a rule to follow it is not practical.
>> 
>> > AFAIK, include/qemu/error-report.h is the historical failed experiment
>> > in structured error reporting, while  include/qapi/error.h is the new
>> > preferred error reporting system that everything should be using.
>> 
>> > On this basis, I'd simply say that include/qemu/error-report.h is
>> > legacy code that should no longer be used, and that new code should
>> > use include/qapi/error.h exclusively and existing code converted
>> > where practical.
>> 
>> Mmmm, I've just reviewed both headers and you sound partially right.
>> 
>> AFAIU, "qemu/error-report.h" contains the additional logic to manage "input
>> locations", not present anywhere else. Also, you state that only the reporting
>> functions in "qemu/error.h" should be used.
>> 
>> Since "qemu/error.h" internally uses 'error_report()' (from
>> "qemu/error-report.h"), it includes the input location information
>> (if any). So,
>> I will simply refer to "qemu/error.h" for the general reporting
>> functions, plus
>> the location management functions in "qemu/error-report.h".
>
> I don't think the location management functions need to be pointed
> out as broadly speaking, no patches ever need to use them. It should
> be sufficient to just describe the new error reporting functions
> in no new code will ever want to use them in general. Really we
> only need document the qapi/error.h functions and tell people not
> to use anything else

People *will* need to use error-report.h to report errors to stderr or
HMP monitor in code wherever such reporting is appropriate.

Good examples include handling command line options, HMP command
handlers.

A not so good example would be device emulation code; there we should
arguably use a logging interface instead, which we don't have.

Counter-examples are a QMP command handler, and pretty much any other
code that's expected to pass on its errors for somebody else to handle.

Locations are mostly automatic, but there are cases where you can
improve error message quality by setting the right location.  Underused.
A few examples are visible in grep loc_pop().