Formatting.

1 files changed, 192 insertions, 166 deletions

diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index f355421d2..151a80f6f 100644
--- a/include/freetype/ftsystem.h
+++ b/include/freetype/ftsystem.h
@@ -25,22 +25,25 @@
 
 FT_BEGIN_HEADER
 
-  /**************************************************************************
-   *
-   *  <Section> system_interface
-   *
-   *  <Title> System Interface
-   *
-   *  <Abstract>
-   *     How FreeType manages memory and i/o
-   *
-   *  <Description>
-   *     This section contains various definitions related to memory
-   *     management and i/o access. You'll need to understand this
-   *     information if you want to use a custom memory manager or
-   *     you own input i/o streams
-   *
-   */
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Section>                                                             */
+  /*    system_interface                                                   */
+  /*                                                                       */
+  /* <Title>                                                               */
+  /*    System Interface                                                   */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    How FreeType manages memory and i/o.                               */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    This section contains various definitions related to memory        */
+  /*    management and i/o access.  You need to understand this            */
+  /*    information if you want to use a custom memory manager or you own  */
+  /*    input i/o streams.                                                 */
+  /*                                                                       */
+  /*************************************************************************/
+
 
   /*************************************************************************/
   /*                                                                       */
@@ -48,89 +51,103 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /*************************************************************************/
 
- /**********************************************************************
-  *
-  * @type: FT_Memory
-  *
-  * @description:
-  *   a handle to a given memory manager object, defined with a
-  *   @FT_MemoryRec structure.
-  */
+
+  /*************************************************************************/
+  /*                                                                       */
+  /* @type:                                                                */
+  /*    FT_Memory                                                          */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A handle to a given memory manager object, defined with a          */
+  /*    @FT_MemoryRec structure.                                           */
+  /*                                                                       */
   typedef struct FT_MemoryRec_*  FT_Memory;
 
 
- /**********************************************************************
-  *
-  * @functype: FT_Alloc_Func
-  *
-  * @description:
-  *   a function used to allocate "size" bytes from "memory"
-  *
-  * @input:
-  *   memory :: handle to source memory manager
-  *   size   :: size in bytes to allocate
-  *
-  * @return:
-  *   address of new memory block. 0 in case of failure
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @functype:                                                            */
+  /*    FT_Alloc_Func                                                      */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A function used to allocate `size' bytes from `memory'.            */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*    memory :: A handle to the source memory manager.                   */
+  /*                                                                       */
+  /*    size   :: The size in bytes to allocate.                           */
+  /*                                                                       */
+  /* @return:                                                              */
+  /*    Address of new memory block.  0 in case of failure.                */
+  /*                                                                       */
   typedef void*  (*FT_Alloc_Func)( FT_Memory  memory,
                                    long       size );
 
 
- /**********************************************************************
-  *
-  * @functype: FT_Free_Func
-  *
-  * @description:
-  *   a function used to release a given block of memory
-  *
-  * @input:
-  *   memory :: handle to source memory manager
-  *   block  :: address of target memory block
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @functype:                                                            */
+  /*    FT_Free_Func                                                       */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A function used to release a given block of memory.                */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*    memory :: A handle to the source memory manager.                   */
+  /*                                                                       */
+  /*    block  :: The address of the target memory block.                  */
+  /*                                                                       */
   typedef void   (*FT_Free_Func)( FT_Memory  memory,
                                   void*      block );
 
- /**********************************************************************
-  *
-  * @functype: FT_Realloc_Func
-  *
-  * @description:
-  *   a function used to re-allocate a given block of memory
-  *
-  * @input:
-  *   memory   :: handle to source memory manager
-  *   cur_size :: the block's current size in bytes
-  *   new_size :: the block's requested new size
-  *   block    :: the block's current address
-  *
-  * @return:
-  *   new block address. 0 in case of memory shortage.
-  *
-  * @note:
-  *   note that in case of error, the old block must still be available
-  */
+
+  /*************************************************************************/
+  /*                                                                       */
+  /* @functype:                                                            */
+  /*    FT_Realloc_Func                                                    */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    a function used to re-allocate a given block of memory.            */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*    memory   :: A handle to the source memory manager.                 */
+  /*                                                                       */
+  /*    cur_size :: The block's current size in bytes.                     */
+  /*                                                                       */
+  /*    new_size :: The block's requested new size.                        */
+  /*                                                                       */
+  /*    block    :: The block's current address.                           */
+  /*                                                                       */
+  /* @return:                                                              */
+  /*    New block address.  0 in case of memory shortage.                  */
+  /*                                                                       */
+  /* @note:                                                                */
+  /*   In case of error, the old block must still be available.            */
+  /*                                                                       */
   typedef void*  (*FT_Realloc_Func)( FT_Memory  memory,
                                      long       cur_size,
                                      long       new_size,
                                      void*      block );
 
 
- /**********************************************************************
-  *
-  * @struct: FT_MemoryRec
-  *
-  * @description:
-  *   a structure used to describe a given memory manager to FreeType 2
-  *
-  * @fields:
-  *    user    ::
-  *    alloc   :: 
-  *    free    ::
-  *    realloc ::
-  *
-  */
-  struct FT_MemoryRec_
+  /*************************************************************************/
+  /*                                                                       */
+  /* @struct:                                                              */
+  /*    FT_MemoryRec                                                       */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A structure used to describe a given memory manager to FreeType 2. */
+  /*                                                                       */
+  /* @fields:                                                              */
+  /*    user    :: A generic typeless pointer for user data.               */
+  /*                                                                       */
+  /*    alloc   :: A pointer type to an allocation function.               */
+  /*                                                                       */
+  /*    free    :: A pointer type to an memory freeing function.           */
+  /*                                                                       */
+  /*    realloc :: A pointer type to a reallocation function.              */
+  /*                                                                       */
+  struct  FT_MemoryRec_
   {
     void*            user;
     FT_Alloc_Func    alloc;
@@ -146,26 +163,26 @@ FT_BEGIN_HEADER
   /*************************************************************************/
 
 
- /************************************************************************
-  *
-  * @type: FT_Stream
-  *
-  * @description:
-  *   a handle to an input stream.
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @type:                                                                */
+  /*    FT_Stream                                                          */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A handle to an input stream.                                       */
+  /*                                                                       */
   typedef struct FT_StreamRec_*  FT_Stream;
 
 
-
- /************************************************************************
-  *
-  * @struct: FT_StreamDesc
-  *
-  * @description:
-  *   a union type used to store either a long or a pointer. This is
-  *   used to store a file descriptor or a FILE* in an input stream
-  *
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @struct:                                                              */
+  /*    FT_StreamDesc                                                      */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A union type used to store either a long or a pointer.  This is    */
+  /*    used to store a file descriptor or a FILE* in an input stream.     */
+  /*                                                                       */
   typedef union  FT_StreamDesc_
   {
     long   value;
@@ -174,80 +191,89 @@ FT_BEGIN_HEADER
   } FT_StreamDesc;
 
 
- /************************************************************************
-  *
-  * @functype: FT_Stream_IO
-  *
-  * @description:
-  *   a function used to seek and read data from a given input stream
-  *
-  * @input:
-  *   stream :: handle to source stream
-  *   offset :: offset of read in stream (always from start)
-  *   buffer :: address of read buffer
-  *   count  :: number of bytes to read from the stream
-  *
-  * @return:
-  *   number of bytes effectively read by the stream
-  *
-  * @note:
-  *   this function might be called to perform seek / skip with
-  *   a "count" of 0
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @functype:                                                            */
+  /*    FT_Stream_IO                                                       */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A function used to seek and read data from a given input stream.   */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*    stream :: A handle to the source stream.                           */
+  /*                                                                       */
+  /*    offset :: The offset of read in stream (always from start).        */
+  /*                                                                       */
+  /*    buffer :: The address of the read buffer.                          */
+  /*                                                                       */
+  /*    count  :: The number of bytes to read from the stream.             */
+  /*                                                                       */
+  /* @return:                                                              */
+  /*    The number of bytes effectively read by the stream.                */
+  /*                                                                       */
+  /* @note:                                                                */
+  /*    This function might be called to perform a seek or skip operation  */
+  /*    with a `count' of 0.                                               */
+  /*                                                                       */
   typedef unsigned long  (*FT_Stream_IO)( FT_Stream       stream,
                                           unsigned long   offset,
                                           unsigned char*  buffer,
                                           unsigned long   count );
 
- /************************************************************************
-  *
-  * @functype: FT_Stream_Close
-  *
-  * @description:
-  *   a function used to close a given input stream
-  *
-  * @input:
-  *   stream :: handle to target stream
-  */
+
+  /*************************************************************************/
+  /*                                                                       */
+  /* @functype:                                                            */
+  /*    FT_Stream_Close                                                    */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*    A function used to close a given input stream.                     */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*   stream :: A handle to the target stream.                            */
+  /*                                                                       */
   typedef void  (*FT_Stream_Close)( FT_Stream  stream );
 
 
- /************************************************************************
-  *
-  * @struct: FT_StreamRec
-  *
-  * @description:
-  *   a structure used to describe an input stream
-  *
-  * @input:
-  *   base       :: for memory-based stream, this is the address of the first
-  *                 stream byte in memory. this field should always be set to
-  *                 NULL for disk-based streams.
-  *
-  *   size       :: the stream size in bytes
-  *   pos        :: the current position within the stream
-  *
-  *   descriptor :: this field is a union that can hold an integer or a pointer
-  *                 it is used by stream implementations to store file
-  *                 descriptors or FILE* pointers..
-  *
-  *   pathname   :: this field is completely ignored by FreeType, however,
-  *                 it's often useful during debugging to use it to store
-  *                 the stream's filename, where available
-  *
-  *   read       :: the stream's input function
-  *   close      :: the stream close function
-  *
-  *   memory     :: memory manager to use to preload frames. this is set
-  *                 internally by FreeType and shouldn't be touched by
-  *                 stream implementations
-  *
-  *   cursor     :: this field is set and used internally by FreeType
-  *                 when parsing frames.
-  *
-  *   limit      :: this field is set and used internally by FreeType
-  *                 when parsing frames.
-  */
+  /*************************************************************************/
+  /*                                                                       */
+  /* @struct:                                                              */
+  /*    FT_StreamRec                                                       */
+  /*                                                                       */
+  /* @description:                                                         */
+  /*   A structure used to describe an input stream.                       */
+  /*                                                                       */
+  /* @input:                                                               */
+  /*   base       :: For memory-based streams, this is the address of the  */
+  /*                 first stream byte in memory.  This field should       */
+  /*                 always be set to NULL for disk-based streams.         */
+  /*                                                                       */
+  /*   size       :: The stream size in bytes.                             */
+  /*                                                                       */
+  /*   pos        :: The current position within the stream.               */
+  /*                                                                       */
+  /*   descriptor :: This field is a union that can hold an integer or a   */
+  /*                 pointer.  It is used by stream implementations to     */
+  /*                 store file descriptors or FILE* pointers.             */
+  /*                                                                       */
+  /*   pathname   :: This field is completely ignored by FreeType.         */
+  /*                 However, it is often useful during debugging to use   */
+  /*                 it to store the stream's filename (where available).  */
+  /*                                                                       */
+  /*   read       :: The stream's input function.                          */
+  /*                                                                       */
+  /*   close      :: The stream;s close function.                          */
+  /*                                                                       */
+  /*   memory     :: The memory manager to use to preload frames.  This is */
+  /*                 set internally by FreeType and shouldn't be touched   */
+  /*                 by stream implementations.                            */
+  /*                                                                       */
+  /*   cursor     :: This field is set and used internally by FreeType     */
+  /*                 when parsing frames.                                  */
+  /*                                                                       */
+  /*   limit      :: This field is set and used internally by FreeType     */
+  /*                 when parsing frames.                                  */
+  /*                                                                       */
   struct  FT_StreamRec_
   {
     unsigned char*   base;