diff --git a/docs/usermanual-object-model.xml b/docs/usermanual-object-model.xml
index 7d70c95c1..5faf8f4dc 100644
--- a/docs/usermanual-object-model.xml
+++ b/docs/usermanual-object-model.xml
@@ -172,11 +172,15 @@
they will need to make a duplicate of the original.
- Finally, object constructors (and, indeed, as much of the
- shaping API as possible) will never return
- NULL. Instead, if there is an allocation
- error, each constructor will return an “empty” object
- singleton.
+ Finally, most object constructors return an “empty” object
+ singleton on allocation failure rather than
+ NULL. Constructors whose names end in
+ _or_fail, such as
+ hb_blob_create_or_fail() and
+ hb_blob_create_from_file_or_fail(), instead
+ return NULL on failure. Check their return
+ values before using the objects, and consult each constructor's
+ API Reference documentation for its failure behavior.
These empty-object singletons are inert and safe (although