[HarfBuzz] Some questions for the documentation

[Behdad Esfahbod]

On 16-01-02 05:46 PM, Khaled Hosny wrote:
> Hi,
> 
> I’m trying to document all of buffer functions [1], and somethings are
> no very clear to me.
> 
> * What is the purpose of hb_buffer_get_empty() and how is it different
>   from hb_buffer_create()?

The _get_empty() is a misnomer.  It returns the nil inert singleton object
that will be returned by hb_buffer_create() in out-of-memory situations.  See:


https://docs.google.com/document/d/18hI56KJpvXtwWbc9QSaz9zzhJwIMnrJ-zkAaKS-W-8k/edit#

(the information there also needs to be integrated in the docs.)

In particular:

"""
Finally, constructors (and as much of the API as possible) will never return
NULL.  Instead, upon allocation errors, they will return certain “empty”
object singletons which are inert and safe (even if useless) to pass around.
This avoids having to check for NULL pointers all over the code.  This “empty”
object can typically be accessed using the get_empty() method of the object type.
"""

> * What is the implications of using different cluster levels?
>   My understanding is that level 0 merges clusters of combining marks to
>   their bases, any thing else? And what is the difference between level
>   1 and two?

I'll explain that in detail in the other thread (in response to Deepak).

Thanks,
behdad


> Regards,
> Khaled
> 
> 1. http://behdad.github.io/harfbuzz/harfbuzz-Buffers.html