<div dir="ltr">On 7 January 2014 09:51, 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="HOEnZb"><div class="h5">On 14-01-07 09:16 PM, Werner LEMBERG wrote:<br>
><br>
>> So my question is: what type of documentation do people in the list<br>
>> want to see the most?  In-line function docs in the comments that<br>
>> populate the gtk-docs?<br>
><br>
> Each function needs a description, together with an explanation of all<br>
> parameters, return values, etc., etc. – just think of having a<br>
> HarfBuzz manpage.<br>
><br>
>> Or external documentation that explains how to use Harfbuzz?<br>
><br>
> This is certainly useful, too.  But I consider the `manpage'<br>
> documentation quest more important since there are already showcases<br>
> that demonstrate HarfBuzz quite well.<br>
<br>
</div></div>Sure.  But most of the API is defined in a way that you wouldn't need any<br>
documentation other than the header file to understand.<br>
<br>
For example, there's just no way you need any docs to understand:<br>
<br>
void<br>
hb_set_del_range (hb_set_t       *set,<br>
                  hb_codepoint_t  first,<br>
                  hb_codepoint_t  last);<br>
<br>
or most of the other type methods.<br>
<br>
There are a few number of *core* HB functions that need to be documented, over<br>
and again.  hb_shape() being the main one.  The one you were using wanting it<br>
even more.<br>
<br></blockquote><div><br></div><div>True. Priority is to document the non-obvious API first.</div><div><br></div><div>You mention hb_shape(). We could have that on the top of the list. From the top of your head do you think of anymore?</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I'll try to reprioritize.  But there's just so much time in this life...<br></blockquote><div><br></div><div>I understand, which is why I think we should share this task. I'm happy to write docs, if someone proof checks them.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Cheers, and thanks everyone,<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
behdad<br>
<a href="http://behdad.org/" target="_blank">http://behdad.org/</a><br>
</font></span></blockquote></div><br></div></div>