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