Add optional callback ranch_transport:format_error/1

2 files changed, 18 insertions, 0 deletions

diff --git a/doc/src/guide/transports.asciidoc b/doc/src/guide/transports.asciidoc
index 73747fd..bdccfc9 100644
--- a/doc/src/guide/transports.asciidoc
+++ b/doc/src/guide/transports.asciidoc
@@ -175,3 +175,8 @@ implement the `{active, once}` and the `{active, true}` options.
 If the transport handler doesn't have a native implementation of `sendfile/5` a
 fallback is available, `ranch_transport:sendfile/6`. The extra first argument
 is the transport's module. See `ranch_ssl` for an example.
+
+It is highly recommended for a custom transport handler to implement the
+optional `format_error/1` callback, in order to provide a human-readable
+diagnostic string. Implementing this callback will become mandatory in
+Ranch 3.0.
diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc
index c26d91c..4717281 100644
--- a/doc/src/manual/ranch_transport.asciidoc
+++ b/doc/src/manual/ranch_transport.asciidoc
@@ -47,6 +47,19 @@ Assign a new controlling process to the socket. The
 controlling process is the process that is linked to
 and receives messages from the socket.
 
+=== format_error
+
+[source,erlang]
+----
+format_error(Reason :: term())
+    -> ReasonString :: string()
+----
+
+Format a listen error into a human-readable diagnostic string.
+
+This callback is optional, but implementing it is highly
+recommended. It will become mandatory in Ranch 3.0.
+
 === getopts
 
 [source,erlang]