[llvm] r311147 - Refine report_fatal_error guidance after post-commit review

[Alex Bradbury via llvm-commits]

Author: asb
Date: Thu Aug 17 23:45:34 2017
New Revision: 311147

URL: http://llvm.org/viewvc/llvm-project?rev=311147&view=rev
Log:
Refine report_fatal_error guidance after post-commit review

Use text suggested by Justin Bogner in post-commit review of r311146 
<http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20170814/479898.html>, 
which makes it clear that report_fatal_error shouldn't be used when there is a 
practicable alternative. Also make this clearer in CodingStandards.

Modified:
    llvm/trunk/docs/CodingStandards.rst
    llvm/trunk/docs/ProgrammersManual.rst

Modified: llvm/trunk/docs/CodingStandards.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.rst?rev=311147&r1=311146&r2=311147&view=diff
==============================================================================
--- llvm/trunk/docs/CodingStandards.rst (original)
+++ llvm/trunk/docs/CodingStandards.rst Thu Aug 17 23:45:34 2017
@@ -1233,9 +1233,10 @@ code for this branch. If the compiler do
 to the "abort" implementation.
 
 Neither assertions or ``llvm_unreachable`` will abort the program on a release
-build. If the error condition can be triggered by user input, then the
-recoverable error mechanism described in :doc:`ProgrammersManual` or
-``report_fatal_error`` should be used instead.
+build. If the error condition can be triggered by user input then the
+recoverable error mechanism described in :doc:`ProgrammersManual` should be
+used instead. In cases where this is not practical, ``report_fatal_error`` may
+be used.
 
 Another issue is that values used only by assertions will produce an "unused
 value" warning when assertions are disabled.  For example, this code will warn:

Modified: llvm/trunk/docs/ProgrammersManual.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=311147&r1=311146&r2=311147&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.rst (original)
+++ llvm/trunk/docs/ProgrammersManual.rst Thu Aug 17 23:45:34 2017
@@ -443,11 +443,12 @@ recovery.
 
 .. 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.
+   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.
 
 Recoverable errors are modeled using LLVM's ``Error`` scheme. This scheme
 represents errors using function return values, similar to classic C integer