diff --git a/docs/usermanual-object-model.xml b/docs/usermanual-object-model.xml index 23065bf76..74986dbf1 100644 --- a/docs/usermanual-object-model.xml +++ b/docs/usermanual-object-model.xml @@ -12,7 +12,7 @@ HarfBuzz features two kinds of data types: non-opaque, pass-by-value types and opaque, heap-allocated types. This kind of separation is common in C libraries that have to provide - API/ABI compatibility (almost) indefinitely. + API/ABI compatibility (almost) indefinitely. Value types: The non-opaque, pass-by-value @@ -32,8 +32,8 @@ possible future members. As such, it’s important to provide equal(), and hash() methods for such structs, allowing users of the API do - effectively deal with the type without having to - adapt their code to future changes. + effectively deal with the type without having to + adapt their code to future changes. Important value types provided by HarfBuzz include the structs @@ -42,7 +42,7 @@ OpenType properties. - +
Objects in HarfBuzz @@ -63,7 +63,7 @@ the hb_buffer_t object has hb_buffer_create() as its constructor, hb_buffer_reference() to reference, and - hb_buffer_destroy() to dereference. + hb_buffer_destroy() to dereference. After construction, each object's properties are accessible only @@ -110,11 +110,11 @@ - +
- - + +
Object lifecycle management @@ -131,7 +131,7 @@ 1. Client programs can increase the reference count on an object by calling its reference() method. Whenever a client - program is finished with an object, it should call its + program is finished with an object, it should call its corresponding destroy() method. The destroy method will decrease the reference count on the object and, whenever the reference count reaches zero, it will also destroy @@ -141,8 +141,8 @@ All of HarfBuzz's object-lifecycle-management APIs are thread-safe (unless you compiled HarfBuzz from source with the HB_NO_MT configuration flag), even when the - object as a whole is not thread-safe. - It is also permissible to reference() or to + object as a whole is not thread-safe. + It is also permissible to reference() or to destroy() the NULL value. @@ -160,7 +160,7 @@ as immutable and is_immutable() methods to test whether or not an object is immutable. Attempts to use setter functions on immutable objects will fail silently; see the API - Reference manual for specifics. + Reference manual for specifics. Note also that there are no "make mutable" methods. If client @@ -187,7 +187,7 @@
- +
User data @@ -195,7 +195,7 @@ offer a "user data" mechanism that can be used to attach arbitrary data to the object. User-data attachment can be useful for tying the lifecycles of various pieces of data - together, or for creating language bindings. + together, or for creating language bindings. Each object type has a set_user_data() @@ -220,10 +220,10 @@ existing user_data associated with the specified key. -
+ + + - -
Blobs @@ -238,9 +238,9 @@ you do so in a hb_blob_t wrapper. - This allows you to take advantage of HarffBuzz's + This allows you to take advantage of HarfBuzz's reference-counting and destroy - callbacks. If you allocated the memory for the data using + callbacks. If you allocated the memory for the data using malloc(), you would create the blob using @@ -251,8 +251,8 @@ allocated memory whenever the blob drops its last reference and is deconstructed. Consequently, the user code can stop worrying about freeing memory and let the reference-counting machinery - take care of that. + take care of that.
- +