Minor. Better documentation. Adds TODOs for letter.

7 files changed, 82 insertions, 31 deletions

diff --git a/include/freetype/internal/cffotypes.h b/include/freetype/internal/cffotypes.h
index aaf06687d..73cb159e0 100644
--- a/include/freetype/internal/cffotypes.h
+++ b/include/freetype/internal/cffotypes.h
@@ -61,6 +61,8 @@ FT_BEGIN_HEADER
   {
     FT_GlyphSlotRec  root;
 
+    /* (OT-SVG) Added these here so that CFFGlyphSlot can be cast to
+       TT_GlyphSlot */
     FT_Byte*          svg_document;
     FT_ULong          svg_document_length;
 
diff --git a/include/freetype/internal/sfnt.h b/include/freetype/internal/sfnt.h
index 996cae895..d47827569 100644
--- a/include/freetype/internal/sfnt.h
+++ b/include/freetype/internal/sfnt.h
@@ -312,7 +312,26 @@ FT_BEGIN_HEADER
                               TT_SBit_MetricsRec  *ametrics );
 
 
-  /* OT-SVG to be documented later */
+  /**************************************************************************
+   *
+   * @functype:
+   *   TT_Load_Svg_Doc_Func
+   *
+   * @description:
+   *   Scans the SVG documents list to find the document containing the glyph
+   *   that has the id `glyph<glyph_index>'
+   *
+   * @input:
+   *   glyph ::
+   *     The glyph slot from which pointers to SVG documents list will be
+   *     grabbed. The results will be stored back in the slot too.
+   *
+   *   glyph_index ::
+   *     The index of the glyph that is to be looked up.
+   *
+   * @return:
+   *   FreeType error code.  0 means success.
+   */
   typedef FT_Error
   (*TT_Load_Svg_Doc_Func)( FT_GlyphSlot  glyph,
                            FT_UInt       glyph_index );
diff --git a/include/freetype/internal/tttypes.h b/include/freetype/internal/tttypes.h
index 9ec8a1c96..3539e1865 100644
--- a/include/freetype/internal/tttypes.h
+++ b/include/freetype/internal/tttypes.h
@@ -967,8 +967,8 @@ FT_BEGIN_HEADER
    * This structure/class is defined here because it is common to the
    * following formats: TTF, OpenType-TT, and OpenType-CFF.
    *
-   * Note, however, that the classes TT_Size and `TT_GlyphSlot'(not anymore),
-   * are not shared between font drivers, and are thus defined in `ttobjs.h`.
+   * Note, however, that the class TT_Size is not shared between font driver,
+   * and is thus defined in `ttobjs.h`.
    *
    */
 
@@ -990,12 +990,28 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
-   * @Type:
+   * @type:
    *   TT_GlyphSlotRec_
    *
-   * @Description:
+   * @description:
    *   A glyph slot that inherits from FT_GlyphSlotRec_ but adds more fields
    *
+   * @fields:
+   *   root ::
+   *     Inherits this structure from FT_GlyphSlotRec. See note below.
+   *
+   *   svg_document ::
+   *     A pointer to the SVG Document stream under interest. The stream
+   *     will be in plain text.
+   *
+   *   svg_document_length ::
+   *     The length of the `svg_document' stream.
+   *
+   * @note:
+   *   This structure has been created to accomodate the needs of OT-SVG
+   *   rendering. It inherits from FT_GlyphSlotRect. So that `TT_GlyphSlot'
+   *   can be casted to `FT_GlyphSlot' and behave that way too. It's defined
+   *   here because it is common to OpenType-TTF and OpenType-CFF.
    */
   typedef struct TT_GlyphSlotRec_ 
   {
@@ -1004,14 +1020,8 @@ FT_BEGIN_HEADER
     FT_ULong          svg_document_length;
   } TT_GlyphSlotRec;
 
-  /**************************************************************************
-   *
-   * @Type:
-   *   TT_GlyphSlot
-   *
-   * @Description:
-   *   A handle to a TrueType glyph slot object.
-   */
+
+  /* A handle to a TrueType glyph slot object. */
   typedef struct TT_GlyphSlotRec_*  TT_GlyphSlot;
 
 
diff --git a/src/cff/cffgload.c b/src/cff/cffgload.c
index 4db77971a..95e2fa6c9 100644
--- a/src/cff/cffgload.c
+++ b/src/cff/cffgload.c
@@ -347,8 +347,8 @@
     if ( load_flags & FT_LOAD_SBITS_ONLY )
       return FT_THROW( Invalid_Argument );
 
-    /* OpenType SVG Support Over here */
-    if ( ( load_flags & FT_LOAD_COLOR ) && 
+    /* check for OT-SVG */
+    if ( ( load_flags & FT_LOAD_COLOR ) &&
          ( ((TT_Face)glyph->root.face)->svg ) )
     {
       SFNT_Service  sfnt = (SFNT_Service)(((TT_Face)glyph->root.face)->sfnt);
diff --git a/src/sfnt/sfdriver.c b/src/sfnt/sfdriver.c
index cff8ad69d..b131bf4f1 100644
--- a/src/sfnt/sfdriver.c
+++ b/src/sfnt/sfdriver.c
@@ -1299,7 +1299,7 @@
     sfnt_get_name_id,       /* TT_Get_Name_ID_Func     get_name_id     */
     tt_face_load_svg,       /* TT_Load_Table_Func      load_svg        */
     tt_face_free_svg,       /* TT_Free_Table_Func      free_svg        */
-    tt_face_load_svg_doc
+    tt_face_load_svg_doc    /* TT_Load_Svg_Doc_Func    load_svg_doc    */
   )
 
 
diff --git a/src/sfnt/ttsvg.c b/src/sfnt/ttsvg.c
index 27e82968d..e076ee1e8 100644
--- a/src/sfnt/ttsvg.c
+++ b/src/sfnt/ttsvg.c
@@ -32,6 +32,8 @@
 
 #include "ttsvg.h"
 
+  /* TODO: (OT-SVG) Decide whether to add documentation here or not */
+
   typedef struct Svg_
   {
     FT_UShort  version;           /* Table version (starting at 0)         */
@@ -131,15 +133,16 @@
     FT_Bool    found = FALSE;
     FT_UInt    i     = 0;
 
-    /* For now it's linear search, later convert to binary search */
+    /* TODO: (OT-SVG) Convert to efficient search algorithm        */
+    /* TODO: (OT-SVG) Use Frame Fields here instead of `FT_NEXT_*' */
     for ( i = 0; i < num_entries; i++)
     {
       start_glyph_id = FT_NEXT_USHORT( stream );
       end_glyph_id   = FT_NEXT_USHORT( stream );
       cur_doc_offset = FT_NEXT_ULONG( stream );
       cur_doc_length = FT_NEXT_ULONG( stream );
-      
-      if ( ( glyph_index >= start_glyph_id) && 
+
+      if ( ( glyph_index >= start_glyph_id) &&
            ( glyph_index <= end_glyph_id  ) )
       {
         found = TRUE;
@@ -162,9 +165,9 @@
 
     TT_GlyphSlot glyph = (TT_GlyphSlot) glyph_;
 
-    /* TODO: properly clean stuff here on errors */
+    /* TODO: (OT-SVG) properly clean stuff here on errors */
 
-    FT_Byte*   doc_list;             /* Pointer to the Svg Document List */ 
+    FT_Byte*   doc_list;             /* Pointer to the Svg Document List */
     FT_UShort  num_entries;          /* Total no of entires in doc list  */
 
     FT_ULong   doc_offset;
@@ -176,32 +179,39 @@
     FT_Bool    is_gzip_encoded = FALSE;
 
     FT_Error   error  = FT_Err_Ok;
-    TT_Face    face   = (TT_Face)glyph->root.face;   
+    TT_Face    face   = (TT_Face)glyph->root.face;
     FT_Memory  memory = face->root.memory;
     Svg*       svg    = face->svg;
 
     /* handle svg being 0x0 situation here */
     doc_list     = svg->svg_doc_list;
     num_entries  = FT_NEXT_USHORT( doc_list );
-    
-    error = find_doc( doc_list, num_entries, glyph_index, 
+
+    error = find_doc( doc_list, num_entries, glyph_index,
                                 &doc_offset, &doc_length );
     if ( error != FT_Err_Ok )
       return error;
 
     doc_list = svg->svg_doc_list;   /* Reset to so we can use it again */
     doc_list = (FT_Byte*)( doc_list + doc_offset );
-    
+
     if( ( doc_list[0] == 0x1F ) && ( doc_list[1] == 0x8B )
                                 && ( doc_list[2] == 0x08 ) )
     {
       is_gzip_encoded = TRUE;
+
+      /* get the size of the orignal document. This helps in alotting the
+       * buffer to accomodate the uncompressed version. The last 4 bytes
+       * of the compressed document are equal to orignal_size modulo 2^32.
+       * Since SVG docs will be lesser in size then 2^32, we can use this
+       * accurately. The four bytes are stored in little-endian format.
+       */
       uncomp_size = (FT_ULong)doc_list[doc_length - 1] << 24 |
                     (FT_ULong)doc_list[doc_length - 2] << 16 |
                     (FT_ULong)doc_list[doc_length - 3] << 8  |
                     (FT_ULong)doc_list[doc_length - 4];
       
-      /* TODO: memory allocated here needs to be freed somewhere */
+      /* TODO: (OT-SVG) memory allocated here needs to be freed somewhere */
       uncomp_buffer = (FT_Byte*) memory->alloc(memory, uncomp_size);
       error = FT_Gzip_Uncompress( memory, uncomp_buffer, &uncomp_size,
                                           doc_list,      doc_length  );
@@ -214,11 +224,9 @@
       glyph->svg_document        = uncomp_buffer;
       glyph->svg_document_length = uncomp_size;
       return FT_Err_Ok;
-    } 
+    }
 
     glyph->svg_document        = doc_list;
     glyph->svg_document_length = doc_length;
     return FT_Err_Ok;
   }
-
-  
diff --git a/src/truetype/ttgload.c b/src/truetype/ttgload.c
index 57baf88b1..ac6613e08 100644
--- a/src/truetype/ttgload.c
+++ b/src/truetype/ttgload.c
@@ -2204,6 +2204,10 @@
 
     FT_BBox       bbox;
     FT_Fixed      y_scale;
+
+    /* TODO: (OT-SVG) Temporary hack to accomodate the change
+     * in the `TT_GlyphSlot' made. Rewrite properly
+     */
     TT_GlyphSlot  glyph_ = (TT_GlyphSlot)loader->glyph;
     FT_GlyphSlot  glyph = (FT_GlyphSlot)glyph_;
     TT_Size       size  = loader->size;
@@ -2392,7 +2396,9 @@
     FT_Error            error;
     TT_SBit_MetricsRec  sbit_metrics;
 
-
+    /* (OT-SVG) face assignment changed to accomodate the change in
+     * the structure of TT_GlyphSlot
+     */
     face   = (TT_Face)(glyph->root.face);
     sfnt   = (SFNT_Service)face->sfnt;
     stream = face->root.stream;
@@ -2404,6 +2410,10 @@
                                    stream,
                                    &(glyph->root.bitmap),
                                    &sbit_metrics );
+    /* TODO: (OT-SVG) So many `glyph->root' look ugly. Maybe create a new variable
+     * to make this look good.
+     */
+
     if ( !error )
     {
       (glyph->root).outline.n_points   = 0;
@@ -2782,6 +2792,8 @@
     FT_Error      error;
     TT_LoaderRec  loader;
     SFNT_Service  sfnt;
+
+    /* TODO: (OT-SVG) maybe find a proper way to do this */
     FT_GlyphSlot  glyph = (FT_GlyphSlot)glyph_;
 
     FT_TRACE1(( "TT_Load_Glyph: glyph index %d\n", glyph_index ));
@@ -2886,7 +2898,7 @@
 
 #endif /* TT_CONFIG_OPTION_EMBEDDED_BITMAPS */
 
-    /* OT-SVG part here */
+    /* check for OT-SVG */
     if ( ( load_flags & FT_LOAD_COLOR ) && ( ((TT_Face)glyph->face)->svg ) )
     {
       sfnt = (SFNT_Service)((TT_Face)glyph->face)->sfnt;