[llvm] r311146 - Give guidance on report_fatal_error in CodingStandards.rst and ProgrammersManual.rst

[Alex Bradbury via llvm-commits]

On 18 August 2017 at 07:06, Justin Bogner via llvm-commits
<llvm-commits at lists.llvm.org> wrote:
> Alex Bradbury via llvm-commits <llvm-commits at lists.llvm.org> writes:
>> +.. note::
>> +
>> +   Ideally, the error handling approach described in this section would be
>> +   used throughout LLVM. However, this is not yet the case. For
>> +   non-programmatic errors where the ``Error`` scheme cannot easily be
>> +   applied, ``report_fatal_error`` should be used to call any installed error
>> +   handler and then terminate the program.
>
> I'm not a big fan of the "should be used" wording here, especially with
> the "cannot *easily* be applied" bit. While there are situations where
> report_fatal_error is the best/only option, it really should be treated
> as a last resort and avoided when reasonable. What do you think of
> wording this more like so?

Ack, "cannot easily be applied" was poor wording.

>   .. note::
>
>      While it would be ideal to use this error handling scheme throughout
>      LLVM, there are places where this hasn't been practical to apply. In
>      situations where you absolutely must emit a non-programmatic error and
>      the ``Error`` model isn't workable you can call ``report_fatal_error``,
>      which will call installed error handlers, print a message, and exit the
>      program.
>
> Feel free to rewrite that however, but I'd like to make sure we're
> discouraging the use of report_fatal_error as much as possible.

That does a much better job of getting the intended meaning across!
I've adopted your wording in r311147. Thanks for the feedback, much
appreciated.

Alex