[PATCH] D57503: [doc]Update String Error documentation in Programmer Manual

[James Henderson via Phabricator via llvm-commits]

jhenderson created this revision.
jhenderson added reviewers: lhames, JDevlieghere, vleschuk, wolfgangp.

A while back, `createStringError` was added to provide easier construction of `StringError` instances, especially with formatting options. I noticed today 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.


Repository:
  rL LLVM

https://reviews.llvm.org/D57503

Files:
  docs/ProgrammersManual.rst


Index: docs/ProgrammersManual.rst
===================================================================
--- docs/ProgrammersManual.rst
+++ docs/ProgrammersManual.rst
@@ -656,19 +656,21 @@
 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 @@
 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
 """""""""""""""""""""""""""""""""""""""""""""""""
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D57503.184474.patch
Type: text/x-patch
Size: 1841 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190131/6dc3f075/attachment.bin>