[HarfBuzz] lack of documentation drives me crazy

[Behdad Esfahbod]

Werner.  You are absolutely right.  I'm sorry!  I'll fix that as soon as I'm
back from Haiti.  Promise!

behdad

On 13-06-15 03:14 PM, Werner LEMBERG wrote:
> 
> 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...
> _______________________________________________
> HarfBuzz mailing list
> HarfBuzz at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/harfbuzz
> .
> 

-- 
behdad
http://behdad.org/