[llvm] r286167 - [docs] Add a pointer to ExitOnError to the discussion of handleErrors in the

[Lang Hames via llvm-commits]

Author: lhames
Date: Mon Nov  7 16:33:13 2016
New Revision: 286167

URL: http://llvm.org/viewvc/llvm-project?rev=286167&view=rev
Log:
[docs] Add a pointer to ExitOnError to the discussion of handleErrors in the
programmer's manual.

ExitOnError is often a better alternative to handleErrors for tool code. This
patch makes it easier to find the ExitOnError discussion when reading the
handleErrors section.

Thanks to Peter Collingbourne for the suggestion.


Modified:
    llvm/trunk/docs/ProgrammersManual.rst

Modified: llvm/trunk/docs/ProgrammersManual.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=286167&r1=286166&r2=286167&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.rst (original)
+++ llvm/trunk/docs/ProgrammersManual.rst Mon Nov  7 16:33:13 2016
@@ -469,8 +469,8 @@ a variadic list of "handlers", each of w
 function, lambda, or class with a call operator) with one argument. The
 ``handleErrors`` function will visit each handler in the sequence and check its
 argument type against the dynamic type of the error, running the first handler
-that matches. This is the same process that is used for catch clauses in C++
-exceptions.
+that matches. This is the same decision process that is used decide which catch
+clause to run for a C++ exception.
 
 Since the list of handlers passed to ``handleErrors`` may not cover every error
 type that can occur, the ``handleErrors`` function also returns an Error value
@@ -500,6 +500,11 @@ elsewhere in the program can easily turn
 into a non-exhaustive list, risking unexpected program termination. Where
 possible, use handleErrors and propagate unknown errors up the stack instead.
 
+For tool code, where errors can be handled by printing an error message then
+exiting with an error code, the :ref:`ExitOnError <err_exitonerr>` utility
+may be a better choice than handleErrors, as it simplifies control flow when
+calling fallible functions.
+
 StringError
 """""""""""
 
@@ -580,6 +585,8 @@ actually recognises three different form
 Any error returned from a handler will be returned from the ``handleErrors``
 function so that it can be handled itself, or propagated up the stack.
 
+.. _err_exitonerr:
+
 Using ExitOnError to simplify tool code
 """""""""""""""""""""""""""""""""""""""