WT-2107: Add example code including an event handler

Clean up thread-safe vs. global "display error strings" documentation:
the global code snippet was wrong, there wasn't a java thread-safe
snippet, add a mention of the thread-safe API to the error-handling
page, quit trying to enumerate the underlying strerror(3) standards.

2 files changed, 17 insertions, 7 deletions

diff --git a/src/docs/error-handling.dox b/src/docs/error-handling.dox
index 08fecd7f709..8ff3b68d64c 100644
--- a/src/docs/error-handling.dox
+++ b/src/docs/error-handling.dox
@@ -55,11 +55,18 @@ This error is generated when wiredtiger_open is configured to return an error if
 @if IGNORE_BUILT_BY_API_ERR_END
 @endif
 
-The ::wiredtiger_strerror function returns the standard message
-associated with any WiredTiger, ISO C99, or POSIX 1003.1-2001 function:
+@section error_translation Translating errors
+
+The WT_SESSION::strerror and ::wiredtiger_strerror functions return the
+standard text message associated with any WiredTiger, ISO C, or POSIX
+standard API.
+
+@snippet ex_all.c Display an error thread safe
 
 @snippet ex_all.c Display an error
 
+Note that ::wiredtiger_strerror is not thread-safe.
+
 @m_if{c}
 @section error_handling_event Error handling using the WT_EVENT_HANDLER
 
diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in
index 338b95c8208..32def98b5e2 100644
--- a/src/include/wiredtiger.in
+++ b/src/include/wiredtiger.in
@@ -828,7 +828,8 @@ struct __wt_session {
 	 * @snippet ex_all.c Display an error thread safe
 	 *
 	 * @param session the session handle
-	 * @param error a return value from a WiredTiger function
+	 * @param error a return value from a WiredTiger, ISO C, or POSIX
+	 * standard API
 	 * @returns a string representation of the error
 	 */
 	const char *__F(strerror)(WT_SESSION *session, int error);
@@ -2434,11 +2435,12 @@ int wiredtiger_open(const char *home,
     WT_CONNECTION **connectionp);
 
 /*!
- * Return information about a WiredTiger error as a string, not thread-safe.
+ * Return information about a WiredTiger error as a string (see
+ * WT_SESSION::strerror for a thread-safe API).
  *
  * @snippet ex_all.c Display an error
  *
- * @param error a return value from a WiredTiger call
+ * @param error a return value from a WiredTiger, ISO C, or POSIX standard API
  * @returns a string representation of the error
  */
 const char *wiredtiger_strerror(int error);
@@ -2491,8 +2493,9 @@ struct __wt_event_handler {
 	 * @param session the WiredTiger session handle in use when the error
 	 * was generated. The handle may have been created by the application
 	 * or automatically by WiredTiger.
-	 * @param error a WiredTiger, C99 or POSIX error code, which can
-	 * be converted to a string using ::wiredtiger_strerror
+	 * @param error a return value from a WiredTiger, ISO C, or
+	 * POSIX standard API, which can be converted to a string using
+	 * WT_SESSION::strerror
 	 * @param message an error string
 	 */
 	int (*handle_error)(WT_EVENT_HANDLER *handler,