From 8456354f6470f40d0af094883ba58342364446d3 Mon Sep 17 00:00:00 2001 From: Lang Hames Date: Sun, 30 Apr 2017 17:24:52 +0000 Subject: [PATCH] [docs] Simplify some language for Error/cantFail in the programmer's manual. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@301773 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 4fb67e1e6d5..d115a9cf6de 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -776,22 +776,21 @@ readability. Using cantFail to simplify safe callsites """"""""""""""""""""""""""""""""""""""""" -Some functions may only fail for a subset of their inputs. For such functions -call-sites using known-safe inputs can assume that the result will be a success -value. +Some functions may only fail for a subset of their inputs, so calls using known +safe inputs can be assumed to succeed. The cantFail functions encapsulate this by wrapping an assertion that their argument is a success value and, in the case of Expected, unwrapping the -T value from the Expected argument: +T value: .. code-block:: c++ - Error mayFail(int X); - Expected mayFail2(int X); + Error onlyFailsForSomeXValues(int X); + Expected onlyFailsForSomeXValues2(int X); void foo() { - cantFail(mayFail(KnownSafeValue)); - int Y = cantFail(mayFail2(KnownSafeValue)); + cantFail(onlyFailsForSomeXValues(KnownSafeValue)); + int Y = cantFail(onlyFailsForSomeXValues2(KnownSafeValue)); ... } @@ -801,8 +800,8 @@ terminate the program on an error input, cantFile simply asserts that the result is success. In debug builds this will result in an assertion failure if an error is encountered. In release builds the behavior of cantFail for failure values is undefined. As such, care must be taken in the use of cantFail: clients must be -certain that a cantFail wrapped call really can not fail under any -circumstances. +certain that a cantFail wrapped call really can not fail with the given +arguments. Use of the cantFail functions should be rare in library code, but they are likely to be of more use in tool and unit-test code where inputs and/or