<div dir="ltr">On 7 January 2014 02:01, Behdad Esfahbod <span dir="ltr"><<a href="mailto:behdad@behdad.org" target="_blank">behdad@behdad.org</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im">On 14-01-05 02:25 PM, Werner LEMBERG wrote:<br>
><br>
>>> Doh.  Thanks, it works now.  It's *really* time that HarfBuzz gets<br>
>>> documented :-)<br>
>><br>
>> That's definitely true.  But Werner, you being FreeType maintainer<br>
>> of over a decade, I don't agree with you this time.  *You* should<br>
>> know that a parameter called "glyphs" takes glyph indices, not<br>
>> Unicode characters...<br>
><br>
> Yep, my fault.  I was distracted by the `hb_codepoint_t' type.<br>
<br>
</div>Right.  Yeah, we use that type for both Unicode codepoints and glyph indices.<br>
<div class="im"><br>
<br>
>> That said, I also want to add that the documentation infrastructure<br>
>> is fully in place and all that is missing is content.  Anyway can<br>
>> document a function or two and send a me patch / pull request.<br>
><br>
> If you open some cans full of time for me, I would immediately start<br>
> with that.<br>
<br>
</div>Well, same here unfortunately :)<br>
<div class="im"><br>
<br>
>   However, I think that you are the very person who should<br>
> add raw documentation (this is, adding one or two sentences to roughly<br>
> describe each function); other people like me could then polish that.<br>
<br>
</div>I wasn't addressing you necessarily.  There are many other people on this list<br>
who are well qualified to document the API.  In fact, I believe people who<br>
have been using the API are in a much better position to propose documentation<br>
(which I would then proof-read) than me who designed those to begin with.<br>
<div class="im"><br>
<br>
> It's *not* fun to be forced to check the sources in case a function<br>
> parameter is not obvious – and the obviousness differs enormously<br>
> between you and me, since you are the author...<br>
<br>
</div>Right, but then there are people like Luis who are taking their time reading<br>
HB code for the sake of learning...<br>
<span class="HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>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.</div>
<div><br></div><div>I've noticed the documentation need and have mentioned it before, and updated the wiki a bit while I was reading it.</div><div><br></div><div>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.</div>
<div><br></div><div><sorry, this is going off-topic from the original thread></div><div><br></div><div>So my question is: what type of documentation do people in the list want to see the most?</div><div>In-line function docs in the comments that populate the gtk-docs? Or external documentation that explains how to use Harfbuzz? or something else?</div>
<div>Is anybody willing to proof check the documentation I write?</div><div><br></div><div>Cheers,</div><div>Luis</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="HOEnZb"><font color="#888888">
behdad<br>
</font></span></blockquote></div><br></div></div>