From 691e2426f4f1f43074b9241d35dcff811e796ee4 Mon Sep 17 00:00:00 2001
From: David Turner <david@freetype.org>
Date: Wed, 10 Jan 2001 06:53:49 +0000
Subject: [PATCH] improved the docmaker script

---
 ChangeLog                   |   5 +
 docs/docmaker.py            | 233 ++++++++++++++++++++++++++++--------
 include/freetype/freetype.h |  65 ++--------
 include/freetype/ftimage.h  |  32 ++++-
 include/freetype/ftlist.h   |  19 ++-
 include/freetype/ftoutln.h  |  15 +++
 include/freetype/ftsystem.h | 177 ++++++++++++++++++++++++++-
 include/freetype/fttypes.h  |  71 +++++++++++
 include/freetype/tttables.h |  17 +++
 9 files changed, 525 insertions(+), 109 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f9ab14090..b1215b7f9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2000-01-09  David Turner <david.turner@freetype.org>
+
+	* docs/docmaker.py: improved script to generate table of contents and
+	index pages.
+
 2000-01-04  Werner Lemberg  <wl@gnu.org>
 
 	* include/freetype/ttnameid.h: Updated Unicode code range comments.
diff --git a/docs/docmaker.py b/docs/docmaker.py
index d961c2055..c3b367db0 100644
--- a/docs/docmaker.py
+++ b/docs/docmaker.py
@@ -18,7 +18,6 @@ html_header = """
 <style content="text/css">
   P { text-align=justify }
   H1 { text-align=center }
-  H2 { text-align=center }
   LI { text-align=justify }
 </style>
 </header>
@@ -55,13 +54,20 @@ code_footer = """
 para_header = "<p>"
 para_footer = "</p>"
 
-block_header = """<center><hr width="550"><table width="550"><tr><td>"""
-block_footer = "</table></center>"
+block_header = """<center><hr width="750"><table width="750"><tr><td>"""
+block_footer = "</td></tr></table></center>"
 
-source_header = """<center><table width="550"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
+description_header = """<center><table width="650"><tr><td>"""
+description_footer = """</td></tr></table></center><br>"""
+
+marker_header = """<center><table width="650" cellpadding=5><tr bgcolor="#EEEEFF"><td><em><b>"""
+marker_inter  = "</b></em></td></tr><tr><td>"
+marker_footer = "</td></tr></table></center>"
+
+source_header = """<center><table width="650"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
 """
 source_footer = """</pre></table></center>
-<br><br>
+<br>
 """
 
 
@@ -213,6 +219,7 @@ class DocCode:
 #
 # The paragraph is filled line by line by the parser.
 #
+
 class DocParagraph:
 
     def __init__( self ):
@@ -314,6 +321,7 @@ class DocParagraph:
 # pass a list of input text lines in the "lines_list" parameter.
 #
 #
+
 class DocContent:
 
     def __init__( self, lines_list ):
@@ -467,7 +475,7 @@ class DocContent:
 
             else:
                 if not in_table:
-                    print "<table cellpadding=4><tr valign=top><td>"
+                    print '<table cellpadding=4><tr valign=top><td>'
                     in_table = 1
                 else:
                     print "</td></tr><tr valign=top><td>"
@@ -481,6 +489,31 @@ class DocContent:
             print "</td></tr></table>"
 
 
+    def dump_html_in_table( self ):
+        n        = len( self.items )
+        in_table = 0
+
+        for i in range( n ):
+            item  = self.items[i]
+            field = item[0]
+
+            if not field:
+                if item[1]:
+                    print "<tr><td colspan=2>"
+                    for element in item[1]:
+                        element.dump_html()
+                    print "</td></tr>"
+
+            else:
+                print "<tr><td><b>" + field + "</b></td><td>"
+
+                for element in item[1]:
+                    element.dump_html()
+
+                print "</td></tr>"
+
+
+
 ######################################################################################
 #
 #
@@ -494,14 +527,21 @@ class DocContent:
 #   "self.source" is simply a list of text lines taken from the
 #   uncommented source itself.
 #
-#   Finally, "self.identifier" is a simple identifier used to
-#   uniquely identify the block.
+#   Finally, "self.name" is a simple identifier used to
+#   uniquely identify the block. it is taken from the first word of the first
+#   paragraphe of the first marker of a given block, i.e:
+#
+#      <Type> Goo
+#      <Description> Bla bla bla
+#
+#   will have a name of "Goo"
 #
 class DocBlock:
 
     def __init__( self, block_line_list = [], source_line_list = [] ):
-        self.items  = []                 # current ( marker, contents ) list
-        self.identifier = None
+        self.items      = []             # current ( marker, contents ) list
+        self.section    = None           # section this block belongs to
+        
         marker      = None               # current marker
         content     = []                 # current content lines list
         alphanum    = string.letters + string.digits + "_"
@@ -572,8 +612,6 @@ class DocBlock:
         if l > 0 and marker:
             content = DocContent( lines )
             self.items.append( ( string.lower( marker ), content ) )
-            if not self.identifier:
-                self.identifier = content.get_identifier()
 
     
     def find_content( self, marker ):
@@ -594,14 +632,20 @@ class DocBlock:
         types = [ 'type', 'struct', 'functype', 'function', 'constant',
                   'enum', 'macro' ]
 
+        parameters = [ 'input', 'inout', 'output', 'return' ]
+
         if not self.items:
             return
 
+        # place html anchor when needed
+        if self.name:
+            print '<a name="'+self.name+'">'
+
         # start of a block
         #
         print block_header
 
-        print "<h2>" + self.identifier + "</h2>"
+        print "<h4>" + self.name + "</h4>"
 
         # print source code
         #
@@ -617,6 +661,8 @@ class DocBlock:
             print  line
         print source_footer
 
+        in_table = 0
+        
         # dump each (marker,content) element
         #
         for element in self.items:
@@ -624,17 +670,19 @@ class DocBlock:
             content = element[1]
 
             if marker == "description":
-                print "<ul>"
+                print description_header
                 content.dump_html()
-                print "</ul>"
+                print description_footer
 
             elif not ( marker in types ):
-                print "<h4>" + marker + "</h4>"
-                print "<ul>"
-                content.dump_html()
-                print "</ul>"
 
-            print ""
+                print marker_header
+                print marker
+                print marker_inter
+                content.dump_html()
+                print marker_footer
+                
+        print ""
 
         print block_footer
 
@@ -649,6 +697,8 @@ class DocBlock:
 #
 #   <Section> Basic_Data_Types
 #
+#   <Title> FreeType 2 Basic Data Types
+#
 #   <Abstract>
 #      Definitions of basic FreeType data types
 #
@@ -663,11 +713,6 @@ class DocSection:
         self.name        = string.lower( block.name )
         self.abstract    = block.find_content( "abstract" )
         self.description = block.find_content( "description" )
-        title_content    = block.find_content( "title" )
-        if title_content:
-            self.title   = title_content.get_title()
-        else:
-            self.titles  = "UNKNOWN_SECTION_TITLE!"
         self.elements    = {}
         self.list        = []
         self.filename    = self.name + ".html"
@@ -722,6 +767,7 @@ class DocSectionList:
         self.sections        = {}
         self.list            = []
         self.current_section = None
+        self.index           = []    # sorted list of blocks that are not sections
 
 
     def append_section( self, block ):
@@ -748,6 +794,7 @@ class DocSectionList:
                 #
                 section.abstract    = abstract
                 section.description = block.find_content( "description" )
+                section.block       = block
 
         else:
             # a new section
@@ -755,7 +802,7 @@ class DocSectionList:
             section = DocSection( block )
             self.sections[name] = section
             self.list.append( section )
-
+            
         self.current_section = section
 
 
@@ -768,11 +815,44 @@ class DocSectionList:
             elif self.current_section:
                 # sys.stderr.write( "  new block" )
                 self.current_section.add_element( block )
+                block.section = self.current_section
+                self.index.append( block )
+
+
+    def prepare_files( self, file_prefix = None ):
+        # prepare the section list, by computing section filenames
+        # and the index
+        if file_prefix:
+            prefix = file_prefix + "-"
+        else:
+            prefix = ""
+
+        # compute section names
+        for section in self.sections.values():
+            title_content     = section.block.find_content( "title" )
+            if title_content:
+                section.title = title_content.get_title()
+            else:
+                section.title = "UNKNOWN_SECTION_TITLE!"
+
+        # compute section filenames        
+        for section in self.sections.values():
+            section.filename = prefix + section.name + ".html"
 
+        self.toc_filename   = prefix + "toc.html"
+        self.index_filename = prefix + "index.html"
+
+        # compute the sorted block list for the index
+        self.index.sort( block_lexicographical_compare )
+        
 
     def dump_html_toc( self ):
         # dump an html table of contents
         #
+        old_stdout = sys.stdout
+        new_file   = open( self.toc_filename, "w" )
+        sys.stdout = new_file
+        
         print html_header
 
         print "<center><h1>Table of Contents</h1></center>"
@@ -790,24 +870,64 @@ class DocSectionList:
 
         print html_footer
 
+        sys.stdout = old_stdout
+
 
     def dump_html_sections( self ):
         old_stdout = sys.stdout
+
         for section in self.sections.values():
-            new_file   = open( section.filename, "w" )
-            sys.stdout = new_file
-            section.dump_html()
-            new_file.close()
+            
+            if section.filename:
+                new_file   = open( section.filename, "w" )
+                sys.stdout = new_file
+                section.dump_html()
+                new_file.close()
 
         sys.stdout = old_stdout
 
 
+    def dump_html_index( self ):
+        
+        old_stdout = sys.stdout
+        new_file   = open( self.index_filename, "w" )
+        sys.stdout = new_file
+
+        num_columns = 3
+        total       = len( self.index )
+        line        = 0
+
+        print html_header
+
+        print "<center><h1>General Index</h1></center>"
+
+        print "<center><table cellpadding=5><tr valign=top><td>"
+
+        for block in self.index:
+
+            print '<a href="'+block.section.filename+'#'+block.name+'">'
+            print block.name
+            print "</a><br>"
+
+            if line*num_columns >= total:
+                print "</td><td>"
+                line = 0
+            else:
+                line = line+1
+
+        print "</tr></table></center>"
+
+        print html_footer
+        
+        sys.stdout = old_stdout
+        
 
 # Filter a given list of DocBlocks. Returns a new list
 # of DocBlock objects that only contains element whose
 # "type" (i.e. first marker) is in the "types" parameter.
 #
-def filter_blocks( block_list, types ):
+def filter_blocks_by_type( block_list, types ):
+
     new_list = []
     for block in block_list:
         if block.items:
@@ -819,17 +939,21 @@ def filter_blocks( block_list, types ):
     return new_list
 
 
+def filter_section_blocks( block ):
+    return block.section != None
+
+
 # Perform a lexicographical comparison of two DocBlock
 # objects. Returns -1, 0 or 1.
 #
 def block_lexicographical_compare( b1, b2 ):
-    if not b1.identifier:
+    if not b1.name:
         return -1
-    if not b2.identifier:
+    if not b2.name:
         return 1
 
-    id1 = string.lower( b1.identifier )
-    id2 = string.lower( b2.identifier )
+    id1 = string.lower( b1.name )
+    id2 = string.lower( b2.name )
 
     if id1 < id2:
         return -1
@@ -839,15 +963,6 @@ def block_lexicographical_compare( b1, b2 ):
         return 1
 
 
-def block_make_list( source_block_list ):
-    list = []
-
-    for block in source_block_list:
-        docblock = DocBlock( block[0], block[1] )
-        list.append( docblock )
-
-    return list
-
 
 # dump a list block as a single HTML page
 #
@@ -862,7 +977,7 @@ def dump_html_1( block_list ):
 
 
 
-def make_block_list():
+def make_block_list_inner():
     """parse a file and extract comments blocks from it"""
 
     list   = []
@@ -1013,6 +1128,21 @@ def make_block_list():
     return list
 
 
+# create a list of DocBlock elements
+#
+def make_block_list():
+    
+    source_block_list = make_block_list_inner()
+    list              = []
+
+    for block in source_block_list:
+        docblock = DocBlock( block[0], block[1] )
+        list.append( docblock )
+
+    return list
+
+
+
 # This function is only used for debugging
 #
 def dump_block_list( list ):
@@ -1029,17 +1159,26 @@ def dump_block_list( list ):
 
 def main( argv ):
     """main program loop"""
+
+    # we begin by simply building a list of DocBlock elements
+    #
     sys.stderr.write( "extracting comment blocks from sources...\n" )
     list = make_block_list()
-    list = block_make_list(list)
 
+    # now, sort the blocks into sections
+    #
     section_list = DocSectionList()
     for block in list:
         section_list.append_block( block )
 
+    section_list.prepare_files( "ft2" )
+
+    # dump the section list TOC and sections
+    #
     section_list.dump_html_toc()
     section_list.dump_html_sections()
-
+    section_list.dump_html_index()
+    
     # list2 = filter_blocks( list, ['type','macro','enum','constant', 'functype'] )
     # list2 = list
     # list2.sort( block_lexicographical_compare )
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index e9d1c440a..e6d55e4be 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -55,6 +55,18 @@ FT_BEGIN_HEADER
   /*************************************************************************/
   /*************************************************************************/
 
+  /*************************************************************************
+   *
+   * <Section> Base_Interface
+   *
+   * <Title> Base Interface
+   *
+   * <Abstract>
+   *    The FreeType 2 base font interface
+   *
+   * <Description>
+   *    This sections details the public high-level API of FreeType 2
+   */
 
   /*************************************************************************/
   /*                                                                       */
@@ -99,59 +111,6 @@ FT_BEGIN_HEADER
   } FT_Glyph_Metrics;
 
 
-  /*************************************************************************/
-  /*                                                                       */
-  /* <FuncType>                                                            */
-  /*    FT_Generic_Finalizer                                               */
-  /*                                                                       */
-  /* <Description>                                                         */
-  /*    Describes a function used to destroy the `client' data of any      */
-  /*    FreeType object.  See the description of the FT_Generic type for   */
-  /*    details of usage.                                                  */
-  /*                                                                       */
-  /* <Input>                                                               */
-  /*    The address of the FreeType object which is under finalization.    */
-  /*    Its client data is accessed through its `generic' field.           */
-  /*                                                                       */
-  typedef void  (*FT_Generic_Finalizer)(void*  object);
-
-
-  /*************************************************************************/
-  /*                                                                       */
-  /* <Struct>                                                              */
-  /*    FT_Generic                                                         */
-  /*                                                                       */
-  /* <Description>                                                         */
-  /*    Client applications often need to associate their own data to a    */
-  /*    variety of FreeType core objects.  For example, a text layout API  */
-  /*    might want to associate a glyph cache to a given size object.      */
-  /*                                                                       */
-  /*    Most FreeType object contains a `generic' field, of type           */
-  /*    FT_Generic, which usage is left to client applications and font    */
-  /*    servers.                                                           */
-  /*                                                                       */
-  /*    It can be used to store a pointer to client-specific data, as well */
-  /*    as the address of a `finalizer' function, which will be called by  */
-  /*    FreeType when the object is destroyed (for example, the previous   */
-  /*    client example would put the address of the glyph cache destructor */
-  /*    in the `finalizer' field).                                         */
-  /*                                                                       */
-  /* <Fields>                                                              */
-  /*    data      :: A typeless pointer to any client-specified data. This */
-  /*                 field is completely ignored by the FreeType library.  */
-  /*                                                                       */
-  /*    finalizer :: A pointer to a `generic finalizer' function, which    */
-  /*                 will be called when the object is destroyed.  If this */
-  /*                 field is set to NULL, no code will be called.         */
-  /*                                                                       */
-  typedef struct  FT_Generic_
-  {
-    void*                 data;
-    FT_Generic_Finalizer  finalizer;
-
-  } FT_Generic;
-
-
   /*************************************************************************/
   /*                                                                       */
   /* <Struct>                                                              */
diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h
index 660848e66..3a8138fcb 100644
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -33,6 +33,11 @@
 
 FT_BEGIN_HEADER
 
+  /***********************************************************************
+   *
+   * <Section> Basic_Types
+   *
+   */
 
   /*************************************************************************/
   /*                                                                       */
@@ -226,6 +231,12 @@ FT_BEGIN_HEADER
   } FT_Bitmap;
 
 
+  /***********************************************************************
+   *
+   * <Section> outline_processing
+   *
+   */
+
   /*************************************************************************/
   /*                                                                       */
   /* <Struct>                                                              */
@@ -346,7 +357,8 @@ FT_BEGIN_HEADER
 
   } FT_Outline_Flags;
 
-
+  /* */
+  
 #define FT_CURVE_TAG( flag )  ( flag & 3 )
 
 #define FT_Curve_Tag_On           1
@@ -516,6 +528,12 @@ FT_BEGIN_HEADER
   } FT_Outline_Funcs;
 
 
+  /***********************************************************************
+   *
+   * <Section> Basic_Types
+   *
+   */
+
   /*************************************************************************/
   /*                                                                       */
   /* <Macro>                                                               */
@@ -594,6 +612,18 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /*************************************************************************/
 
+  /************************************************************************
+   *
+   *  <Section> Raster
+   *
+   *  <Title> Scanline converter
+   *
+   *  <Abstract>
+   *     How vectorial outlines are converted into bitmaps and pixmaps
+   *
+   *  <Description>
+   *     This section contains technical definitions
+   */
 
   /*************************************************************************/
   /*                                                                       */
diff --git a/include/freetype/ftlist.h b/include/freetype/ftlist.h
index a3d60a393..4d4397c9e 100644
--- a/include/freetype/ftlist.h
+++ b/include/freetype/ftlist.h
@@ -34,7 +34,21 @@
 
 FT_BEGIN_HEADER
 
-
+  /**************************************************************************
+   *
+   *  <Section> list_processing
+   *
+   *  <Title> List Processing
+   *
+   *  <Abstract>
+   *     simple management of lists
+   *
+   *  <Description>
+   *     This section contains various definitions related to list processing
+   *     using doubly-linked nodes.
+   *
+   */
+  
   /*************************************************************************/
   /*                                                                       */
   /* <Function>                                                            */
@@ -213,7 +227,8 @@ FT_BEGIN_HEADER
                                        FT_Memory           memory,
                                        void*               user );
 
-
+  /* */
+  
 FT_END_HEADER
 
 #endif /* __FTLIST_H__ */
diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h
index 258f472d7..9c16ca1d1 100644
--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -27,6 +27,21 @@
 
 FT_BEGIN_HEADER
 
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Section> outline_processing                                          */
+  /*                                                                       */
+  /* <Title> Outline Processing                                            */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    Functions to create, transform and render vectorial glyph images   */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    This sections contains routines used to create and destroy         */
+  /*    scalable glyph images known as "outlines". These can also be       */
+  /*    measured, transformed and converted into bitmaps, pixmaps and      */
+  /*                                                                       */
+  /*                                                                       */
 
   /*************************************************************************/
   /*                                                                       */
diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index 1a963d9d0..802a61ea5 100644
--- a/include/freetype/ftsystem.h
+++ b/include/freetype/ftsystem.h
@@ -25,6 +25,22 @@
 
 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
+   *
+   */
 
   /*************************************************************************/
   /*                                                                       */
@@ -32,22 +48,88 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /*************************************************************************/
 
-
+ /**********************************************************************
+  *
+  * @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
+  */
   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
+  */
   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
+  */
   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_
   {
     void*            user;
@@ -64,6 +146,26 @@ FT_BEGIN_HEADER
   /*************************************************************************/
 
 
+ /************************************************************************
+  *
+  * @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
+  *
+  */
   typedef union  FT_StreamDesc_
   {
     long   value;
@@ -72,17 +174,80 @@ FT_BEGIN_HEADER
   } FT_StreamDesc;
 
 
-  typedef struct FT_StreamRec_*  FT_Stream;
-
-
+ /************************************************************************
+  *
+  * @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
+  */
   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
+  */
   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_
   {
     unsigned char*   base;
@@ -90,8 +255,7 @@ FT_BEGIN_HEADER
     unsigned long    pos;
 
     FT_StreamDesc    descriptor;
-    FT_StreamDesc    pathname;    /* ignored by FreeType -- */
-                                  /* useful for debugging   */
+    FT_StreamDesc    pathname;
     FT_Stream_IO     read;
     FT_Stream_Close  close;
 
@@ -100,6 +264,7 @@ FT_BEGIN_HEADER
     unsigned char*   limit;
   };
 
+  /* */
 
 FT_END_HEADER
 
diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h
index 83ddbc2c6..51c64ea20 100644
--- a/include/freetype/fttypes.h
+++ b/include/freetype/fttypes.h
@@ -29,6 +29,19 @@
 
 FT_BEGIN_HEADER
 
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Section> Basic_Types                                                 */
+  /*                                                                       */
+  /* <Title> Basic Data Types                                              */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    The basic data types defined by the library                        */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    This sections contains the basic data types defined by FreeType 2, */
+  /*    rangine from simple scalar types to font specific ones             */
+  /*                                                                       */
 
   /*************************************************************************/
   /*                                                                       */
@@ -275,6 +288,60 @@ FT_BEGIN_HEADER
   } FT_Matrix;
 
 
+  /*************************************************************************/
+  /*                                                                       */
+  /* <FuncType>                                                            */
+  /*    FT_Generic_Finalizer                                               */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    Describes a function used to destroy the `client' data of any      */
+  /*    FreeType object.  See the description of the FT_Generic type for   */
+  /*    details of usage.                                                  */
+  /*                                                                       */
+  /* <Input>                                                               */
+  /*    The address of the FreeType object which is under finalization.    */
+  /*    Its client data is accessed through its `generic' field.           */
+  /*                                                                       */
+  typedef void  (*FT_Generic_Finalizer)(void*  object);
+
+
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Struct>                                                              */
+  /*    FT_Generic                                                         */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    Client applications often need to associate their own data to a    */
+  /*    variety of FreeType core objects.  For example, a text layout API  */
+  /*    might want to associate a glyph cache to a given size object.      */
+  /*                                                                       */
+  /*    Most FreeType object contains a `generic' field, of type           */
+  /*    FT_Generic, which usage is left to client applications and font    */
+  /*    servers.                                                           */
+  /*                                                                       */
+  /*    It can be used to store a pointer to client-specific data, as well */
+  /*    as the address of a `finalizer' function, which will be called by  */
+  /*    FreeType when the object is destroyed (for example, the previous   */
+  /*    client example would put the address of the glyph cache destructor */
+  /*    in the `finalizer' field).                                         */
+  /*                                                                       */
+  /* <Fields>                                                              */
+  /*    data      :: A typeless pointer to any client-specified data. This */
+  /*                 field is completely ignored by the FreeType library.  */
+  /*                                                                       */
+  /*    finalizer :: A pointer to a `generic finalizer' function, which    */
+  /*                 will be called when the object is destroyed.  If this */
+  /*                 field is set to NULL, no code will be called.         */
+  /*                                                                       */
+  typedef struct  FT_Generic_
+  {
+    void*                 data;
+    FT_Generic_Finalizer  finalizer;
+
+  } FT_Generic;
+
+
+
   /*************************************************************************/
   /*                                                                       */
   /* <Macro>                                                               */
@@ -299,6 +366,10 @@ FT_BEGIN_HEADER
   /*************************************************************************/
   /*************************************************************************/
 
+  /**************************************************************************
+   *
+   *  <Section> list_processing
+   */
 
   /*************************************************************************/
   /*                                                                       */
diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index dbbcc1603..557fd2ca6 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -27,6 +27,19 @@
 
 FT_BEGIN_HEADER
 
+  /*************************************************************************/
+  /*                                                                       */
+  /* <Section> TrueType_Tables                                             */
+  /*                                                                       */
+  /* <Title> TrueType Tables                                               */
+  /*                                                                       */
+  /* <Abstract>                                                            */
+  /*    TrueType-specific table types and functions                        */
+  /*                                                                       */
+  /* <Description>                                                         */
+  /*    This sections contains the definition of TrueType-specific tables  */
+  /*    as well as some routines used to access and process them.          */
+  /*                                                                       */
 
   /*************************************************************************/
   /*                                                                       */
@@ -520,6 +533,8 @@ FT_BEGIN_HEADER
   } TT_MaxProfile;
 
 
+  /* */
+
   typedef enum
   {
     ft_sfnt_head = 0,
@@ -569,6 +584,8 @@ FT_BEGIN_HEADER
                                          FT_Sfnt_Tag  tag );
 
 
+  /* */
+
 FT_END_HEADER
 
 #endif /* __TTTABLES_H__ */