FT2 method naming conventions

[Just van Rossum]

At 1:50 PM +0100 10-03-2000, David Turner wrote:
>  I have recently re-formatted lots of FreeType sources in order to
>  make the famous "FT_<Object>_<Method>" reformatting you suggested.

Cool.

>  It hasn't been very difficult, but I'd like to say that I'm not
>  incredibly satisfied with the results. What really bothers me is
>  that many functions are methods of the face object, though they
>  really act on inside "FT_Size" or "FT_Glyph" objects.

It they really act on FT_Size and FT_Glyph objects that are owned and
managed by the *face* object, then they are in fact FT_Face methods, aren't
they? No problem with that for me.

>  For example :
>
>   FT_Set_Char_Size  & FT_Load_Glyph can be translated either to:
>
>      FT_Size_Set( face, ... )
>      FT_Glyph_Load( face, ... )
>
>   or
>
>      FT_Face_Set_Size( face, ... )
>      FT_Face_Load_Glyph( face, ... )
>
>   The first case is confusing, at best, for most novice users, because the
>   first argument isn't a "size" or "glyph". The second isn't too bad,
>   but nearly all functions are methods of a FT_Face, and I find it
>   really redundant.

It is... As I wrote, I really think FT_Face is a special case since it's
the top level object type (disregarding the library object of course).

I'd say, stick with FT_Set_Size() and FT_Load_Glyph().

>  So, could people in the list tell me which way they prefer, or if they
>  simply do not want to see the API fuctions names changed. My opinion is
>  that the current interface is clear and simple to understand, even if
>  it's not completely OO to the death ..

Sure! I completely agree practicality is more important than consistency to
the max...

Here's some output of the script I'm writing to help me create the Python
interface, listed by first argument, which in most cases is the object type
of which the function is a method:

FT_Face:
- FT_Attach_File
- FT_Attach_Stream
- FT_Done_Face
- FT_New_Size
- FT_Set_Char_Size
- FT_Set_Pixel_Sizes
- FT_New_GlyphSlot
- FT_Load_Glyph
- FT_Load_Char
- FT_Get_Glyph_Bitmap
- FT_Get_Kerning
- FT_Select_Charmap
- FT_Set_Charmap
- FT_Get_Char_Index
FT_GlyphSlot:
- FT_Done_GlyphSlot
FT_Library:
- FT_Done_FreeType
- FT_New_Face
- FT_Open_Face
- FT_New_Outline
- FT_Done_Outline
- FT_Set_Raster
- FT_Set_Raster_Mode
- FT_Get_Outline_Bitmap
FT_Library*:
- FT_Init_FreeType
FT_Long:
- FT_MulDiv
- FT_MulFix
- FT_DivFix
FT_Matrix*:
- FT_Matrix_Multiply
- FT_Matrix_Invert
FT_Outline*:
- FT_Decompose_Outline
- FT_Get_Outline_CBox
- FT_Translate_Outline
- FT_Copy_Outline
- FT_Transform_Outline
FT_Pos*:
- FT_Transform_Vector
FT_Raster:
- FT_Raster_Init
- FT_Raster_Render
- FT_Raster_SetPalette
FT_Size:
- FT_Done_Size


(FT_Transform_Vector is odd: it takes two FT_Pos args instead of one
FT_Vector arg)

Most names are good as they are, the ones I'd like to see changed are these:

FT_Outline*:
- FT_Decompose_Outline -> FT_Outline_Decompose
- FT_Get_Outline_CBox -> FT_Outline_Get_CBox
- FT_Translate_Outline -> FT_Outline_Translate
- FT_Copy_Outline -> FT_Outline_Copy
- FT_Transform_Outline -> FT_Outline_Transform

FT_Pos* (or rather FT_Vector* ;-):
- FT_Transform_Vector -> FT_Vector_Transform

Erm, that's it I think...

Just