[HarfBuzz] lack of documentation drives me crazy

[Werner LEMBERG]

Behdad,


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 :-(

While the source code is written very cleanly, the purpose of it is
not as obvious as you might think.  For example, what's the difference
between

  hb_ft_font_create
  hb_ft_face_create

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?

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

IMHO, providing at least a skeleton documentation (i.e., short
sentences which describe the various functions and structures with a
few words) is *essential*, and I call it a really critical bug that
absolutely nothing is available.  And no, the stuff in the `util'
directory is not a valid substitute for lack of documentation, since
those examples aren't documented either (and written in high-level,
non-trivial C++ code).


    Werner


PS: IIRC, I've asked for documentation already a few times...