[HarfBuzz] HarfBuzz API design

[Carl Worth]

Excerpts from Behdad Esfahbod's message of Wed Aug 19 12:53:19 -0700 2009:
> On 08/19/2009 02:45 PM, Carl Worth wrote:
>
> Humm, seems like s/writeable/writable/g is also needed.  Stupid me.  The geek 
> inside me prefers writeable though.

This is actually one reason I was trying to eliminate that word
altogether from the naming. :-)

It's definitely easier to just not have any ambiguous spelling cases
in the first place.

> That's definitely one of the most arbitrary parts of the code, thanks for 
> catching!  I do think there's a slight confusion though, which if I clarify 
> (as the docs will eventually will), the values make more sense.  Look at it 
> this way, the mode parameter describes the characteristics of the input data 
> only.  It's not a property of the blob itself, and for that reason there is no 
> getter for it.

OK. That much wasn't clear, certainly...

> 
>  >>     HB_MEMORY_MODE_READONLY_NEVER_DUPLICATE,
> 
> As it also describe a behavior of the blob itself.  That value however is for 
> very corner case uses (when you're just interested in knowing whether the data 
> is sane and you want to avoid the cost of copying).

Particularly due to that value.

> I also did some Hoffman encoding here.  I initially had READONLY and 
> READONLY_MAY_DUPLICATE, but figured that READONLY_MAY_DUPLICATE is what I want 
> most users to use, and one should think twice before using READONLY.  So I 
> gave the short name to the common one and made the corner case use a longer
> name.

I do appreciate this! It's nice to have short names for the common
cases.

> I found the flag approach even more confusing as one would then think about 
> (and the docs have to explain) all different kind of combinations.

Yes. You're probably right that a single enum is going to be better.

> I wanted to keep MPROTECT out of the name.  Again, please think about it again 
> without the mode determining whether the blob will be writeable or not.  Just 
> as describing the access mode of the input data only.  Do you think the 
> current enum makes sense that way?

Well, if the READONLY_NEVER_DUPLICATE case didn't exist, then it all
makes perfect sense, yes.

But with that value present, there *is* at least one mode (if rarely
used) where the resulting blob has write operations disabled. And it
still seems a little odd that code with:

      hb_blob_create (... HB_MEMORY_MODEL_READONLY ...);

doesn't create such a blob.

No matter. With improved documentation it's likely all just
fine. You've clearly thought a lot about the names already, and that's
really all that I can ask. :-)

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/harfbuzz/attachments/20090819/4d7a4d27/attachment.pgp>