[HarfBuzz] problem with hb_ot_layout_lookup_would_substitute

[Luis de Bethencourt]

On 7 January 2014 02:01, Behdad Esfahbod <behdad at behdad.org> wrote:

> On 14-01-05 02:25 PM, Werner LEMBERG wrote:
> >
> >>> Doh.  Thanks, it works now.  It's *really* time that HarfBuzz gets
> >>> documented :-)
> >>
> >> That's definitely true.  But Werner, you being FreeType maintainer
> >> of over a decade, I don't agree with you this time.  *You* should
> >> know that a parameter called "glyphs" takes glyph indices, not
> >> Unicode characters...
> >
> > Yep, my fault.  I was distracted by the `hb_codepoint_t' type.
>
> Right.  Yeah, we use that type for both Unicode codepoints and glyph
> indices.
>
>
> >> That said, I also want to add that the documentation infrastructure
> >> is fully in place and all that is missing is content.  Anyway can
> >> document a function or two and send a me patch / pull request.
> >
> > If you open some cans full of time for me, I would immediately start
> > with that.
>
> Well, same here unfortunately :)
>
>
> >   However, I think that you are the very person who should
> > add raw documentation (this is, adding one or two sentences to roughly
> > describe each function); other people like me could then polish that.
>
> I wasn't addressing you necessarily.  There are many other people on this
> list
> who are well qualified to document the API.  In fact, I believe people who
> have been using the API are in a much better position to propose
> documentation
> (which I would then proof-read) than me who designed those to begin with.
>
>
> > It's *not* fun to be forced to check the sources in case a function
> > parameter is not obvious – and the obviousness differs enormously
> > between you and me, since you are the author...
>
> Right, but then there are people like Luis who are taking their time
> reading
> HB code for the sake of learning...
>
>
Yes, I'm reading the code since I find it very interesting and the design
of it based on ADT well thought. Yet I understand most people that look
into Harfbuzz don't want to dive that deep and want to "just use it".
Besides being busy, like we all are, and having higher urgencies in their
current projects that depend on using it.

I've noticed the documentation need and have mentioned it before, and
updated the wiki a bit while I was reading it.

I've been considering writing more documentation myself, it is a task that
blends well with learning the code. Slows down the speed of reading but it
enhances the level of understanding. So I could take on this after I finish
my current hb_set_t task, or during. The good thing about documentation is
it can be done by divide-and-conquer.

<sorry, this is going off-topic from the original thread>

So my question is: what type of documentation do people in the list want to
see the most?
In-line function docs in the comments that populate the gtk-docs? Or
external documentation that explains how to use Harfbuzz? or something else?
Is anybody willing to proof check the documentation I write?

Cheers,
Luis


> behdad
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/harfbuzz/attachments/20140107/f9544796/attachment-0001.html>