ref: 8ec9dfd99185fce2b397bce7cfae2106f8ba0295
parent: 90a03301421ee470aea404955c4069ebac324173
author: Werner Lemberg <[email protected]>
date: Tue Nov 7 18:56:02 EST 2000
Moving doc comments for BASE functions from source to header files.
--- a/include/freetype/ftlist.h
+++ b/include/freetype/ftlist.h
@@ -34,24 +34,95 @@
#endif
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Find */
+ /* */
+ /* <Description> */
+ /* Finds the list node for a given listed object. */
+ /* */
+ /* <Input> */
+ /* list :: A pointer to the parent list. */
+ /* data :: The address of the listed object. */
+ /* */
+ /* <Return> */
+ /* List node. NULL if it wasn't found. */
+ /* */
FT_EXPORT( FT_ListNode ) FT_List_Find( FT_List list,
void* data );
- FT_EXPORT( void ) FT_List_Add ( FT_List list,
- FT_ListNode node );
- FT_EXPORT( void ) FT_List_Insert ( FT_List list,
- FT_ListNode node );
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Add */
+ /* */
+ /* <Description> */
+ /* Appends an element to the end of a list. */
+ /* */
+ /* <InOut> */
+ /* list :: A pointer to the parent list. */
+ /* node :: The node to append. */
+ /* */
+ FT_EXPORT( void ) FT_List_Add( FT_List list,
+ FT_ListNode node );
- FT_EXPORT( void ) FT_List_Remove ( FT_List list,
- FT_ListNode node );
- FT_EXPORT( void ) FT_List_Up ( FT_List list,
- FT_ListNode node );
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Insert */
+ /* */
+ /* <Description> */
+ /* Inserts an element at the head of a list. */
+ /* */
+ /* <InOut> */
+ /* list :: A pointer to parent list. */
+ /* node :: The node to insert. */
+ /* */
+ FT_EXPORT( void ) FT_List_Insert( FT_List list,
+ FT_ListNode node );
/*************************************************************************/
/* */
+ /* <Function> */
+ /* FT_List_Remove */
+ /* */
+ /* <Description> */
+ /* Removes a node from a list. This function doesn't check whether */
+ /* the node is in the list! */
+ /* */
+ /* <Input> */
+ /* node :: The node to remove. */
+ /* */
+ /* <InOut> */
+ /* list :: A pointer to the parent list. */
+ /* */
+ FT_EXPORT( void ) FT_List_Remove( FT_List list,
+ FT_ListNode node );
+
+
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Up */
+ /* */
+ /* <Description> */
+ /* Moves a node to the head/top of a list. Used to maintain LRU */
+ /* lists. */
+ /* */
+ /* <InOut> */
+ /* list :: A pointer to the parent list. */
+ /* node :: The node to move. */
+ /* */
+ FT_EXPORT( void ) FT_List_Up( FT_List list,
+ FT_ListNode node );
+
+
+ /*************************************************************************/
+ /* */
/* <FuncType> */
/* FT_List_Iterator */
/* */
@@ -69,6 +140,26 @@
void* user );
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Iterate */
+ /* */
+ /* <Description> */
+ /* Parses a list and calls a given iterator function on each element. */
+ /* Note that parsing is stopped as soon as one of the iterator calls */
+ /* returns a non-zero value. */
+ /* */
+ /* <Input> */
+ /* list :: A handle to the list. */
+ /* iterator :: An interator function, called on each node of the */
+ /* list. */
+ /* user :: A user-supplied field which is passed as the second */
+ /* argument to the iterator. */
+ /* */
+ /* <Return> */
+ /* The result (a FreeType error code) of the last iterator call. */
+ /* */
FT_EXPORT( FT_Error ) FT_List_Iterate( FT_List list,
FT_List_Iterator iterator,
void* user );
@@ -97,6 +188,25 @@
void* user );
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_List_Finalize */
+ /* */
+ /* <Description> */
+ /* Destroys all elements in the list as well as the list itself. */
+ /* */
+ /* <Input> */
+ /* list :: A handle to the list. */
+ /* */
+ /* destroy :: A list destructor that will be applied to each element */
+ /* of the list. */
+ /* */
+ /* memory :: The current memory object which handles deallocation. */
+ /* */
+ /* user :: A user-supplied field which is passed as the last */
+ /* argument to the destructor. */
+ /* */
FT_EXPORT( void ) FT_List_Finalize( FT_List list,
FT_List_Destructor destroy,
FT_Memory memory,
--- a/include/freetype/internal/ftmemory.h
+++ b/include/freetype/internal/ftmemory.h
@@ -56,15 +56,91 @@
/*************************************************************************/
/*************************************************************************/
+
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_Alloc */
+ /* */
+ /* <Description> */
+ /* Allocates a new block of memory. The returned area is always */
+ /* zero-filled; this is a strong convention in many FreeType parts. */
+ /* */
+ /* <Input> */
+ /* memory :: A handle to a given `memory object' which handles */
+ /* allocation. */
+ /* */
+ /* size :: The size in bytes of the block to allocate. */
+ /* */
+ /* <Output> */
+ /* P :: A pointer to the fresh new block. It should be set to */
+ /* NULL if `size' is 0, or in case of error. */
+ /* */
+ /* <Return> */
+ /* FreeType error code. 0 means success. */
+ /* */
FT_BASE( FT_Error ) FT_Alloc( FT_Memory memory,
FT_Long size,
- void** P );
+ void* *P );
+
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_Realloc */
+ /* */
+ /* <Description> */
+ /* Reallocates a block of memory pointed to by `*P' to `Size' bytes */
+ /* from the heap, possibly changing `*P'. */
+ /* */
+ /* <Input> */
+ /* memory :: A handle to a given `memory object' which handles */
+ /* reallocation. */
+ /* */
+ /* current :: The current block size in bytes. */
+ /* */
+ /* size :: The new block size in bytes. */
+ /* */
+ /* <InOut> */
+ /* P :: A pointer to the fresh new block. It should be set to */
+ /* NULL if `size' is 0, or in case of error. */
+ /* */
+ /* <Return> */
+ /* FreeType error code. 0 means success. */
+ /* */
+ /* <Note> */
+ /* All callers of FT_Realloc() _must_ provide the current block size */
+ /* as well as the new one. */
+ /* */
FT_BASE( FT_Error ) FT_Realloc( FT_Memory memory,
FT_Long current,
FT_Long size,
void** P );
+
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_Free */
+ /* */
+ /* <Description> */
+ /* Releases a given block of memory allocated through FT_Alloc(). */
+ /* */
+ /* <Input> */
+ /* memory :: A handle to a given `memory object' which handles */
+ /* memory deallocation */
+ /* */
+ /* P :: This is the _address_ of a _pointer_ which points to the */
+ /* allocated block. It is always set to NULL on exit. */
+ /* */
+ /* <Return> */
+ /* FreeType error code. 0 means success. */
+ /* */
+ /* <Note> */
+ /* If P or *P are NULL, this function should return successfully. */
+ /* This is a strong convention within all of FreeType and its */
+ /* drivers. */
+ /* */
FT_BASE( void ) FT_Free( FT_Memory memory,
void** P );
--- a/include/freetype/internal/ftobjs.h
+++ b/include/freetype/internal/ftobjs.h
@@ -338,9 +338,43 @@
FT_EXPORT( FT_Error ) FT_Done_Size( FT_Size size );
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_New_GlyphSlot */
+ /* */
+ /* <Description> */
+ /* It is sometimes useful to have more than one glyph slot for a */
+ /* given face object. This function is used to create additional */
+ /* slots. All of them are automatically discarded when the face is */
+ /* destroyed. */
+ /* */
+ /* <Input> */
+ /* face :: A handle to a parent face object. */
+ /* */
+ /* <Output> */
+ /* aslot :: A handle to a new glyph slot object. */
+ /* */
+ /* <Return> */
+ /* FreeType error code. 0 means success. */
+ /* */
FT_BASE( FT_Error ) FT_New_GlyphSlot( FT_Face face,
- FT_GlyphSlot* aslot );
+ FT_GlyphSlot *aslot );
+
+ /*************************************************************************/
+ /* */
+ /* <Function> */
+ /* FT_Done_GlyphSlot */
+ /* */
+ /* <Description> */
+ /* Destroys a given glyph slot. Remember however that all slots are */
+ /* automatically destroyed with its parent. Using this function is */
+ /* not always mandatory. */
+ /* */
+ /* <Input> */
+ /* slot :: A handle to a target glyph slot. */
+ /* */
FT_BASE( void ) FT_Done_GlyphSlot( FT_GlyphSlot slot );
@@ -409,10 +443,10 @@
FT_BASE( FT_Error ) FT_GlyphLoader_New( FT_Memory memory,
- FT_GlyphLoader** aloader );
+ FT_GlyphLoader* *aloader );
FT_BASE( FT_Error ) FT_GlyphLoader_Create_Extra(
- FT_GlyphLoader* loader );
+ FT_GlyphLoader* loader );
FT_BASE( void ) FT_GlyphLoader_Done( FT_GlyphLoader* loader );
--- a/src/base/ftlist.c
+++ b/src/base/ftlist.c
@@ -38,21 +38,8 @@
#define FT_COMPONENT trace_list
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Find */
- /* */
- /* <Description> */
- /* Finds the list node for a given listed object. */
- /* */
- /* <Input> */
- /* list :: A pointer to the parent list. */
- /* data :: The address of the listed object. */
- /* */
- /* <Return> */
- /* List node. NULL if it wasn't found. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( FT_ListNode ) FT_List_Find( FT_List list,
void* data )
{
@@ -72,18 +59,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Add */
- /* */
- /* <Description> */
- /* Appends an element to the end of a list. */
- /* */
- /* <InOut> */
- /* list :: A pointer to the parent list. */
- /* node :: The node to append. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( void ) FT_List_Add( FT_List list,
FT_ListNode node )
{
@@ -102,18 +79,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Insert */
- /* */
- /* <Description> */
- /* Inserts an element at the head of a list. */
- /* */
- /* <InOut> */
- /* list :: A pointer to parent list. */
- /* node :: The node to insert. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( void ) FT_List_Insert( FT_List list,
FT_ListNode node )
{
@@ -132,21 +99,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Remove */
- /* */
- /* <Description> */
- /* Removes a node from a list. This function doesn't check whether */
- /* the node is in the list! */
- /* */
- /* <Input> */
- /* node :: The node to remove. */
- /* */
- /* <InOut> */
- /* list :: A pointer to the parent list. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( void ) FT_List_Remove( FT_List list,
FT_ListNode node )
{
@@ -168,19 +122,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Up */
- /* */
- /* <Description> */
- /* Moves a node to the head/top of a list. Used to maintain LRU */
- /* lists. */
- /* */
- /* <InOut> */
- /* list :: A pointer to the parent list. */
- /* node :: The node to move. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( void ) FT_List_Up( FT_List list,
FT_ListNode node )
{
@@ -208,26 +151,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Iterate */
- /* */
- /* <Description> */
- /* Parses a list and calls a given iterator function on each element. */
- /* Note that parsing is stopped as soon as one of the iterator calls */
- /* returns a non-zero value. */
- /* */
- /* <Input> */
- /* list :: A handle to the list. */
- /* iterator :: An interator function, called on each node of the */
- /* list. */
- /* user :: A user-supplied field which is passed as the second */
- /* argument to the iterator. */
- /* */
- /* <Return> */
- /* The result (a FreeType error code) of the last iterator call. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( FT_Error ) FT_List_Iterate( FT_List list,
FT_List_Iterator iterator,
void* user )
@@ -252,25 +177,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_List_Finalize */
- /* */
- /* <Description> */
- /* Destroys all elements in the list as well as the list itself. */
- /* */
- /* <Input> */
- /* list :: A handle to the list. */
- /* */
- /* destroy :: A list destructor that will be applied to each element */
- /* of the list. */
- /* */
- /* memory :: The current memory object which handles deallocation. */
- /* */
- /* user :: A user-supplied field which is passed as the last */
- /* argument to the destructor. */
- /* */
+ /* documentation is in ftlist.h */
+
FT_BASE_DEF( void ) FT_List_Finalize( FT_List list,
FT_List_Destructor destroy,
FT_Memory memory,
--- a/src/base/ftobjs.c
+++ b/src/base/ftobjs.c
@@ -48,31 +48,11 @@
#define FT_COMPONENT trace_memory
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Alloc */
- /* */
- /* <Description> */
- /* Allocates a new block of memory. The returned area is always */
- /* zero-filled; this is a strong convention in many FreeType parts. */
- /* */
- /* <Input> */
- /* memory :: A handle to a given `memory object' which handles */
- /* allocation. */
- /* */
- /* size :: The size in bytes of the block to allocate. */
- /* */
- /* <Output> */
- /* P :: A pointer to the fresh new block. It should be set to */
- /* NULL if `size' is 0, or in case of error. */
- /* */
- /* <Return> */
- /* FreeType error code. 0 means success. */
- /* */
+ /* documentation is in ftmemory.h */
+
FT_BASE_DEF( FT_Error ) FT_Alloc( FT_Memory memory,
FT_Long size,
- void** P )
+ void* *P )
{
FT_Assert( P != 0 );
@@ -100,34 +80,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Realloc */
- /* */
- /* <Description> */
- /* Reallocates a block of memory pointed to by `*P' to `Size' bytes */
- /* from the heap, possibly changing `*P'. */
- /* */
- /* <Input> */
- /* memory :: A handle to a given `memory object' which handles */
- /* reallocation. */
- /* */
- /* current :: The current block size in bytes. */
- /* */
- /* size :: The new block size in bytes. */
- /* */
- /* <InOut> */
- /* P :: A pointer to the fresh new block. It should be set to */
- /* NULL if `size' is 0, or in case of error. */
- /* */
- /* <Return> */
- /* FreeType error code. 0 means success. */
- /* */
- /* <Note> */
- /* All callers of FT_Realloc() _must_ provide the current block size */
- /* as well as the new one. */
- /* */
+ /* documentation is in ftmemory.h */
+
FT_BASE_DEF( FT_Error ) FT_Realloc( FT_Memory memory,
FT_Long current,
FT_Long size,
@@ -164,29 +118,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Free */
- /* */
- /* <Description> */
- /* Releases a given block of memory allocated through FT_Alloc(). */
- /* */
- /* <Input> */
- /* memory :: A handle to a given `memory object' which handles */
- /* memory deallocation */
- /* */
- /* P :: This is the _address_ of a _pointer_ which points to the */
- /* allocated block. It is always set to NULL on exit. */
- /* */
- /* <Return> */
- /* FreeType error code. 0 means success. */
- /* */
- /* <Note> */
- /* If P or *P are NULL, this function should return successfully. */
- /* This is a strong convention within all of FreeType and its */
- /* drivers. */
- /* */
+ /* documentation is in ftmemory.h */
+
FT_BASE_DEF( void ) FT_Free( FT_Memory memory,
void** P )
{
@@ -362,7 +295,7 @@
/* create a new glyph loader */
FT_BASE_DEF( FT_Error ) FT_GlyphLoader_New( FT_Memory memory,
- FT_GlyphLoader** aloader )
+ FT_GlyphLoader* *aloader )
{
FT_GlyphLoader* loader;
FT_Error error;
@@ -447,7 +380,7 @@
FT_BASE_DEF( FT_Error ) FT_GlyphLoader_Create_Extra(
- FT_GlyphLoader* loader )
+ FT_GlyphLoader* loader )
{
FT_Error error;
FT_Memory memory = loader->memory;
@@ -479,10 +412,10 @@
/* function reallocates its outline tables if necessary. Note that it */
/* DOESN'T change the number of points within the loader! */
/* */
- FT_BASE_DEF( FT_Error ) FT_GlyphLoader_Check_Points(
- FT_GlyphLoader* loader,
- FT_UInt n_points,
- FT_UInt n_contours )
+ FT_BASE_DEF( FT_Error ) FT_GlyphLoader_Check_Points(
+ FT_GlyphLoader* loader,
+ FT_UInt n_points,
+ FT_UInt n_contours )
{
FT_Memory memory = loader->memory;
FT_Error error = FT_Err_Ok;
@@ -745,28 +678,10 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_New_GlyphSlot */
- /* */
- /* <Description> */
- /* It is sometimes useful to have more than one glyph slot for a */
- /* given face object. This function is used to create additional */
- /* slots. All of them are automatically discarded when the face is */
- /* destroyed. */
- /* */
- /* <Input> */
- /* face :: A handle to a parent face object. */
- /* */
- /* <Output> */
- /* aslot :: A handle to a new glyph slot object. */
- /* */
- /* <Return> */
- /* FreeType error code. 0 means success. */
- /* */
+ /* documentation is in ftobjs.h */
+
FT_BASE_DEF( FT_Error ) FT_New_GlyphSlot( FT_Face face,
- FT_GlyphSlot* aslot )
+ FT_GlyphSlot *aslot )
{
FT_Error error;
FT_Driver driver;
@@ -806,19 +721,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Done_GlyphSlot */
- /* */
- /* <Description> */
- /* Destroys a given glyph slot. Remember however that all slots are */
- /* automatically destroyed with its parent. Using this function is */
- /* not always mandatory. */
- /* */
- /* <Input> */
- /* slot :: A handle to a target glyph slot. */
- /* */
+ /* documentation is in ftobjs.h */
+
FT_BASE_DEF( void ) FT_Done_GlyphSlot( FT_GlyphSlot slot )
{
if ( slot )
@@ -2463,27 +2367,8 @@
}
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Module_Interface */
- /* */
- /* <Description> */
- /* Finds a module and returns its specific interface as a typeless */
- /* pointer. */
- /* */
- /* <Input> */
- /* library :: A handle to the library object. */
- /* */
- /* module_name :: The module's name (as an ASCII string). */
- /* */
- /* <Return> */
- /* A module-specific interface if available, 0 otherwise. */
- /* */
- /* <Note> */
- /* You should better be familiar with FreeType internals to know */
- /* which module to look for, and what its interface is :-) */
- /* */
+ /* documentation is in ftobjs.h */
+
FT_BASE_DEF( const void* ) FT_Get_Module_Interface( FT_Library library,
const char* mod_name )
{
--- a/src/base/ftstream.c
+++ b/src/base/ftstream.c
@@ -636,9 +636,9 @@
}
- FT_BASE_DEF( FT_Error ) FT_Read_Fields( FT_Stream stream,
- const FT_Frame_Field* fields,
- void* structure )
+ FT_BASE_DEF( FT_Error ) FT_Read_Fields( FT_Stream stream,
+ const FT_Frame_Field* fields,
+ void* structure )
{
FT_Error error;
FT_Bool frame_accessed = 0;