[HarfBuzz] lack of documentation drives me crazy

[Cosmin Apreutesei]

> please, PLEASE add some documentation to harfbuzz!  It really drives
> me crazy that I have to read the source code of harfbuzz to get some
> clues.  This is an endless time sink :-(

Hey, I totally share your pain.

Lemme try to answer some of your questions from my very limited
knowledge until Behdad responds.

> For example, what's the difference
> between
>
>   hb_ft_font_create
>   hb_ft_face_create

A hb_ft_face is internal to hb_ft_font and created automatically. It
is needed by the font object to query font metrics and read sfnt
tables. I don't know why you would create one yourself.

> and what's the difference of those two to the
>
>   hb_font_create
>   hb_face_create
>
> functions?  When should I use the former, when the latter?  Or both?
> In which order?

hb_font_create and hb_face_create create "abstract" objects. If you
create them like this, you need to implement and assign a bunch of
callbacks to them to make them work. This way harfbuzz is extendable
so you can use your OS font subsystem instead of freetype for reading
fonts, or hook in to your svg parser so you can use svg fonts, etc.
This is similar to prototype-based inheritance of dynamic laguages.

> Or: What is a blob?  Why should I use it?  Etc., etc.

Check this out:
http://lists.freedesktop.org/archives/harfbuzz/2009-August/000359.html