Give guidance on report_fatal_error in CodingStandards.rst and ProgrammersManual.rst

[asb]

Summary

The current ProgrammersManual.rst document has a lot of well-written documentation on error handling thanks to @lhames. It suggests errors can be split cleanly into "programmatic" and "recoverable" errors. However, the reality in current LLVM seems to be there are a number of cases where a non-programmatic error is not easily recoverable. Therefore, add a note to indicate the existence of report_fatal_error for these cases. I've also added a reminder to CodingStandards.rst in the section on assertions, to indicate that llvm_unreachable and assertions should not be relied upon to report errors triggered by user input.

Thanks to @majnemer for pointing out out my llvm_unreachable abuse in a number of my RISC-V patches.

The ProgrammersManual is also silent on the use of LLVMContext::diagnose, which is used in BPF+WebAssembly+AMDGPU to report some errors during instruction selection. I don't address that in this patch, as it's not quite clear how to fit in to the current error handling story.

[lhames]

Looks good to me. Thanks very much Alex!

docs/CodingStandards.rst

.. code-block:: c++
   llvm_unreachable("Invalid radix for integer literal");
 
 When assertions are enabled, this will print the message if it's ever reached
 and then exit the program. When assertions are disabled (i.e. in release
 builds), ``llvm_unreachable`` becomes a hint to compilers to skip generating
 code for this branch. If the compiler does not support this, it will fall back
 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.
+
 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:
 
 .. code-block:: c++
 
   unsigned Size = V.size();
   assert(Size > 42 && "Vector smaller than it should be");
 

docs/ProgrammersManual.rst

 
 Recoverable errors represent an error in the program's environment, for example
 a resource failure (a missing file, a dropped network connection, etc.), or
 malformed input. These errors should be detected and communicated to a level of
 the program where they can be handled appropriately. Handling the error may be
 as simple as reporting the issue to the user, or it may involve attempts at
 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.
+
 Recoverable errors are modeled using LLVM's ``Error`` scheme. This scheme
 represents errors using function return values, similar to classic C integer
 error codes, or C++'s ``std::error_code``. However, the ``Error`` class is
 actually a lightweight wrapper for user-defined error types, allowing arbitrary
 information to be attached to describe the error. This is similar to the way C++
 exceptions allow throwing of user-defined types.
 
 Success values are created by calling ``Error::success()``, E.g.: