Leave some more breadcrumbs in docs for error-handling libssl's error-handling is one of the most difficult things to get right with this API. Leave some more notes, in case the reader does not know what "error queue" means. Change-Id: I91464ccdc12bf9e05ac9ed61930bc733244a9b36 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/70929 Commit-Queue: Bob Beck <bbe@google.com> Auto-Submit: David Benjamin <davidben@google.com> Commit-Queue: David Benjamin <davidben@google.com> Reviewed-by: Bob Beck <bbe@google.com>

diff --git a/API-CONVENTIONS.md b/API-CONVENTIONS.md
index 5c891dd..93506e9 100644
--- a/API-CONVENTIONS.md
+++ b/API-CONVENTIONS.md

@@ -40,7 +40,15 @@
 As with `errno`, callers must test the function's return value, not the error
 queue to determine whether an operation failed. Some codepaths may not interact
 with the error queue, and the error queue may have state from a previous failed
-operation.
+operation. After checking for failure, the caller can then inspect the error
+queue in the failure case for details.
+
+As a notable exception, some functions in the SSL/TLS library use a multi-step
+process to indicate failure: First, the return value indicates whether the
+operation failed. Then, `SSL_get_error` indicates whether the failure was due to
+an error (`SSL_ERROR_SSL`) or some recoverable condition (e.g.
+`SSL_ERROR_WANT_READ`). In the former case, the caller can use the error queue
+for more information.
 
 When ignoring a failed operation, it is recommended to call `ERR_clear_error` to
 avoid the state interacting with future operations. Failing to do so should not
@@ -50,7 +58,9 @@
 situation in the future.
 
 Where possible, avoid conditioning on specific reason codes and limit usage to
-logging. The reason codes are very specific and may change over time.
+logging. The reason codes are very fine-grained and tend to leak details of the
+library's internal structure. Changes in the library often have a side effect of
+changing the exact reason code returned.
 
 
 ## Memory allocation

diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index a0797cd..f76e0a1 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h

@@ -478,7 +478,7 @@
 #define SSL_ERROR_NONE 0
 
 // SSL_ERROR_SSL indicates the operation failed within the library. The caller
-// may inspect the error queue for more information.
+// may inspect the error queue (see |ERR_get_error|) for more information.
 #define SSL_ERROR_SSL 1
 
 // SSL_ERROR_WANT_READ indicates the operation failed attempting to read from