From 5cf7a9afd33debb4e8d51973c65e1fb846219cb2 Mon Sep 17 00:00:00 2001
From: Sergiu Deitsch <sergiu.deitsch@gmail.com>
Date: Wed, 12 Jun 2024 23:56:44 +0200
Subject: [PATCH] docs: describe failure writer

---
 docs/failures.md | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/docs/failures.md b/docs/failures.md
index 1fe4d30..7d8a39d 100644
--- a/docs/failures.md
+++ b/docs/failures.md
@@ -21,15 +21,33 @@ from the signal handler.
         @     0x7f892f7ef1c4 (unknown)
         @           0x4046f9 (unknown)
 
-By default, the signal handler writes the failure dump to the standard
-error. You can customize the destination by
-`#!cpp InstallFailureWriter()`.
+
+## Customizing Handler Output
+
+By default, the signal handler writes the failure dump to the standard error.
+However, it is possible to customize the destination by installing a callback
+using the `#!cpp google::InstallFailureWriter()` function. The function expects
+a pointer to a function with the following signature:
+
+``` cpp
+void YourFailureWriter(const char* message/* (1)! */, std::size_t length/* (2)! */);
+```
+
+1. The pointer references the start of the failure message.
+
+    !!! danger
+        The string is **not null-terminated**.
+
+2. The message length in characters.
+
+!!! warning "Possible overflow errors"
+    Users should not expect the `message` string to be null-terminated.
 
 ## User-defined Failure Function
 
 `FATAL` severity level messages or unsatisfied `CHECK` condition
 terminate your program. You can change the behavior of the termination
-by `InstallFailureFunction`.
+by `google::InstallFailureFunction`.
 
 ``` cpp
 void YourFailureFunction() {