[llvm] r352846 - [doc]Update String Error documentation in Programmer Manual

[James Henderson via llvm-commits]

Author: jhenderson
Date: Fri Feb  1 02:02:42 2019
New Revision: 352846

URL: http://llvm.org/viewvc/llvm-project?rev=352846&view=rev
Log:
[doc]Update String Error documentation in Programmer Manual

A while back, createStringError was added to provide easier construction
of StringError instances, especially with formatting options. Prior to
this patch, that the documentation only mentions the standard method of
using it. Since createStringError is slightly shorter to type, and also
provides the formatting options, this patch updates the Programmer's
Manual to use the new function in its examples, and to mention the
printf formatting options. It also fixes a small typo in one of the
examples and removes the unnecessary make_error_code call.

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=352846&r1=352845&r2=352846&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.rst (original)
+++ llvm/trunk/docs/ProgrammersManual.rst Fri Feb  1 02:02:42 2019
@@ -656,19 +656,21 @@ taken is to report them to the user so t
 environment. In this case representing the error as a string makes perfect
 sense. LLVM provides the ``StringError`` class for this purpose. It takes two
 arguments: A string error message, and an equivalent ``std::error_code`` for
-interoperability:
+interoperability. It also provides a ``createStringError`` function to simplify
+common usage of this class:
 
 .. code-block:: c++
 
-  make_error<StringError>("Bad executable",
-                          make_error_code(errc::executable_format_error"));
+  // These two lines of code are equivalent:
+  make_error<StringError>("Bad executable", errc::executable_format_error);
+  createStringError(errc::executable_format_error, "Bad executable");
 
 If you're certain that the error you're building will never need to be converted
 to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function:
 
 .. code-block:: c++
 
-  make_error<StringError>("Bad executable", inconvertibleErrorCode());
+  createStringError(inconvertibleErrorCode(), "Bad executable");
 
 This should be done only after careful consideration. If any attempt is made to
 convert this error to a ``std::error_code`` it will trigger immediate program
@@ -677,6 +679,14 @@ interoperability you should look for an
 can convert to, and even (as painful as it is) consider introducing a new one as
 a stopgap measure.
 
+``createStringError`` can take ``printf`` style format specifiers to provide a
+formatted message:
+
+.. code-block:: c++
+
+  createStringError(errc::executable_format_error,
+                    "Bad executable: %s", FileName);
+
 Interoperability with std::error_code and ErrorOr
 """""""""""""""""""""""""""""""""""""""""""""""""