Documentation fixes.
diff --git a/include/freetype/internal/cffotypes.h b/include/freetype/internal/cffotypes.h
index 32f7d32..570a92e 100644
--- a/include/freetype/internal/cffotypes.h
+++ b/include/freetype/internal/cffotypes.h
@@ -1,3 +1,14 @@
+/***************************************************************************/
+/*                                                                         */
+/*  cffotypes.h                                                            */
+/*                                                                         */
+/*    Basic OpenType/CFF object type definitions (specification).          */
+/*                                                                         */
+/*  Copyright notice here.                                                 */
+/*                                                                         */
+/***************************************************************************/
+
+
 #ifndef CFFOTYPES_H_
 #define CFFOTYPES_H_
 
@@ -84,4 +95,7 @@
 FT_END_HEADER
 
 
-#endif
+#endif /* CFFOTYPES_H_ */
+
+
+/* END */
diff --git a/include/freetype/internal/psaux.h b/include/freetype/internal/psaux.h
index c287974..d37b6e5 100644
--- a/include/freetype/internal/psaux.h
+++ b/include/freetype/internal/psaux.h
@@ -961,7 +961,6 @@
   typedef void
   (*CFF_Builder_Close_Contour_Func)( CFF_Builder*  builder );
 
-  /* static */
   typedef FT_Error
   (*CFF_Builder_Add_Contour_Func)( CFF_Builder*  builder );
 
@@ -969,7 +968,6 @@
 
   typedef struct  CFF_Builder_FuncsRec_
   {
-    /* static */
     void
     (*init)( CFF_Builder*   builder,
              TT_Face        face,
@@ -977,7 +975,6 @@
              CFF_GlyphSlot  glyph,
              FT_Bool        hinting );
 
-    /* static */
     void
     (*done)( CFF_Builder*  builder );
 
diff --git a/include/freetype/internal/services/svcfftl.h b/include/freetype/internal/services/svcfftl.h
index 4663041..a47debf 100644
--- a/include/freetype/internal/services/svcfftl.h
+++ b/include/freetype/internal/services/svcfftl.h
@@ -1,3 +1,14 @@
+/***************************************************************************/
+/*                                                                         */
+/*  svcfftl.h                                                              */
+/*                                                                         */
+/*    The FreeType CFF tables loader service (specification).              */
+/*                                                                         */
+/*  Copyright notice here                                                  */
+/*                                                                         */
+/***************************************************************************/
+
+
 #ifndef SVCFFTL_H_
 #define SVCFFTL_H_
 
diff --git a/src/cid/cidgload.c b/src/cid/cidgload.c
index 2194151..e8a2be3 100644
--- a/src/cid/cidgload.c
+++ b/src/cid/cidgload.c
@@ -383,6 +383,7 @@
     if ( error )
       goto Exit;
 
+    /* Copy flags back for forced scaling */
     hinting     = glyph->hint;
     scaled      = glyph->scaled;
 
diff --git a/src/psaux/cffdecode.c b/src/psaux/cffdecode.c
index dceb916..4fbb9d1 100644
--- a/src/psaux/cffdecode.c
+++ b/src/psaux/cffdecode.c
@@ -1,3 +1,12 @@
+/***************************************************************************/
+/*                                                                         */
+/*  cffdecode.c                                                            */
+/*                                                                         */
+/*    PostScript CFF (Type 2) decoding routines (body).                    */
+/*                                                                         */
+/*  Copyright notice here.                                                 */
+/*                                                                         */
+/***************************************************************************/
 
 
 #include <ft2build.h>
diff --git a/src/psaux/cffdecode.h b/src/psaux/cffdecode.h
index 1b021b7..4243ca6 100644
--- a/src/psaux/cffdecode.h
+++ b/src/psaux/cffdecode.h
@@ -1,3 +1,13 @@
+/***************************************************************************/
+/*                                                                         */
+/*  cffdecode.h                                                            */
+/*                                                                         */
+/*    PostScript CFF (Type 2) decoding routines (specification).           */
+/*                                                                         */
+/*  Copyright notice here.                                                 */
+/*                                                                         */
+/***************************************************************************/
+
 
 #ifndef CFFDECODE_H_
 #define CFFDECODE_H_
diff --git a/src/psaux/psarrst.c b/src/psaux/psarrst.c
index 9bd0997..a878094 100644
--- a/src/psaux/psarrst.c
+++ b/src/psaux/psarrst.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2arrst.c                                                             */
+/*  psarrst.c                                                              */
 /*                                                                         */
 /*    Adobe's code for Array Stacks (body).                                */
 /*                                                                         */
diff --git a/src/psaux/psarrst.h b/src/psaux/psarrst.h
index 095938d..b7d1140 100644
--- a/src/psaux/psarrst.h
+++ b/src/psaux/psarrst.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2arrst.h                                                             */
+/*  psarrst.h                                                              */
 /*                                                                         */
 /*    Adobe's code for Array Stacks (specification).                       */
 /*                                                                         */
diff --git a/src/psaux/psblues.c b/src/psaux/psblues.c
index 9c8b025..ae39d03 100644
--- a/src/psaux/psblues.c
+++ b/src/psaux/psblues.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2blues.c                                                             */
+/*  psblues.c                                                              */
 /*                                                                         */
 /*    Adobe's code for handling Blue Zones (body).                         */
 /*                                                                         */
diff --git a/src/psaux/psblues.h b/src/psaux/psblues.h
index 48e8be8..888de9f 100644
--- a/src/psaux/psblues.h
+++ b/src/psaux/psblues.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2blues.h                                                             */
+/*  psblues.h                                                              */
 /*                                                                         */
 /*    Adobe's code for handling Blue Zones (specification).                */
 /*                                                                         */
diff --git a/src/psaux/pserror.c b/src/psaux/pserror.c
index 7b1d4b5..9169e52 100644
--- a/src/psaux/pserror.c
+++ b/src/psaux/pserror.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2error.c                                                             */
+/*  pserror.c                                                              */
 /*                                                                         */
 /*    Adobe's code for error handling (body).                              */
 /*                                                                         */
diff --git a/src/psaux/pserror.h b/src/psaux/pserror.h
index e2a44b9..4a631b8 100644
--- a/src/psaux/pserror.h
+++ b/src/psaux/pserror.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2error.h                                                             */
+/*  pserror.h                                                              */
 /*                                                                         */
 /*    Adobe's code for error handling (specification).                     */
 /*                                                                         */
diff --git a/src/psaux/psfixed.h b/src/psaux/psfixed.h
index a041184..b931630 100644
--- a/src/psaux/psfixed.h
+++ b/src/psaux/psfixed.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2fixed.h                                                             */
+/*  psfixed.h                                                              */
 /*                                                                         */
 /*    Adobe's code for Fixed Point Mathematics (specification only).       */
 /*                                                                         */
diff --git a/src/psaux/psfont.c b/src/psaux/psfont.c
index 093e66e..ff69b82 100644
--- a/src/psaux/psfont.c
+++ b/src/psaux/psfont.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2font.c                                                              */
+/*  psfont.c                                                               */
 /*                                                                         */
 /*    Adobe's code for font instances (body).                              */
 /*                                                                         */
diff --git a/src/psaux/psfont.h b/src/psaux/psfont.h
index fc86f80..7f53416 100644
--- a/src/psaux/psfont.h
+++ b/src/psaux/psfont.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2font.h                                                              */
+/*  psfont.h                                                               */
 /*                                                                         */
 /*    Adobe's code for font instances (specification).                     */
 /*                                                                         */
diff --git a/src/psaux/psft.c b/src/psaux/psft.c
index b12d9d1..fd09414 100644
--- a/src/psaux/psft.c
+++ b/src/psaux/psft.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2ft.c                                                                */
+/*  psft.c                                                                 */
 /*                                                                         */
 /*    FreeType Glue Component to Adobe's Interpreter (body).               */
 /*                                                                         */
diff --git a/src/psaux/psft.h b/src/psaux/psft.h
index 95e7954..28bc49c 100644
--- a/src/psaux/psft.h
+++ b/src/psaux/psft.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2ft.h                                                                */
+/*  psft.h                                                                 */
 /*                                                                         */
 /*    FreeType Glue Component to Adobe's Interpreter (specification).      */
 /*                                                                         */
diff --git a/src/psaux/psglue.h b/src/psaux/psglue.h
index fba6737..4fa5445 100644
--- a/src/psaux/psglue.h
+++ b/src/psaux/psglue.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2glue.h                                                              */
+/*  psglue.h                                                               */
 /*                                                                         */
 /*    Adobe's code for shared stuff (specification only).                  */
 /*                                                                         */
diff --git a/src/psaux/pshints.c b/src/psaux/pshints.c
index f6234e7..cf40bc0 100644
--- a/src/psaux/pshints.c
+++ b/src/psaux/pshints.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2hints.c                                                             */
+/*  pshints.c                                                              */
 /*                                                                         */
 /*    Adobe's code for handling CFF hints (body).                          */
 /*                                                                         */
diff --git a/src/psaux/pshints.h b/src/psaux/pshints.h
index a898454..02fdc53 100644
--- a/src/psaux/pshints.h
+++ b/src/psaux/pshints.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2hints.h                                                             */
+/*  pshints.h                                                              */
 /*                                                                         */
 /*    Adobe's code for handling CFF hints (body).                          */
 /*                                                                         */
diff --git a/src/psaux/psintrp.c b/src/psaux/psintrp.c
index 3e0590f..61fc8f8 100644
--- a/src/psaux/psintrp.c
+++ b/src/psaux/psintrp.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2intrp.c                                                             */
+/*  psintrp.c                                                              */
 /*                                                                         */
 /*    Adobe's CFF Interpreter (body).                                      */
 /*                                                                         */
@@ -661,6 +661,9 @@
                 op1 == cf2_cmdENDCHAR  ||
                 op1 >= 32 /* Numbers */ ) )
         {
+          /* Skip outline commands first time round.       */
+          /* `endchar' will trigger initial hintmap build  */
+          /* and rewind the charstring.                    */
           cf2_stack_clear( opStack );
           continue;
         }
@@ -787,6 +790,7 @@
           }
         }
 
+        /* Add left-sidebearing correction in Type 1 mode */
         cf2_doStems( font,
                      opStack,
                      &hStemHintArray,
@@ -816,6 +820,7 @@
           }
         }
 
+        /* Add left-sidebearing correction in Type 1 mode */
         cf2_doStems( font,
                      opStack,
                      &vStemHintArray,
@@ -1220,6 +1225,7 @@
                                          SUB_INT32( SUB_INT32( v2, v1 ),
                                                     cf2_stack_getReal( opStack, 3 ) ) );
 
+                      /* Add left-sidebearing correction */
                       cf2_doStems( font,
                                    opStack,
                                    isV ? &vStemHintArray : &hStemHintArray,
@@ -1755,6 +1761,8 @@
 
                       if ( initial_map_ready )
                       {
+                        /* do not clear hints if initial hintmap */
+                        /* is not ready - we need to collate all */
                         cf2_arrstack_clear( &vStemHintArray );
                         cf2_arrstack_clear( &hStemHintArray );
 
diff --git a/src/psaux/psintrp.h b/src/psaux/psintrp.h
index 01809a9..ec22ddc 100644
--- a/src/psaux/psintrp.h
+++ b/src/psaux/psintrp.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2font.h                                                              */
+/*  psintrp.h                                                              */
 /*                                                                         */
 /*    Adobe's CFF Interpreter (specification).                             */
 /*                                                                         */
diff --git a/src/psaux/psobjs.c b/src/psaux/psobjs.c
index d643afe..a62ee23 100644
--- a/src/psaux/psobjs.c
+++ b/src/psaux/psobjs.c
@@ -2409,6 +2409,8 @@
   }
 
 
+  /* Synthesize a SubFont object for Type 1 fonts, for use in the  */
+  /* new interpreter to access Private dict data                   */
   FT_LOCAL_DEF( void )
   t1_make_subfont( FT_Face      face,
                    PS_Private   priv,
diff --git a/src/psaux/psread.c b/src/psaux/psread.c
index 237ab7b..719863c 100644
--- a/src/psaux/psread.c
+++ b/src/psaux/psread.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2read.c                                                              */
+/*  psread.c                                                               */
 /*                                                                         */
 /*    Adobe's code for stream handling (body).                             */
 /*                                                                         */
diff --git a/src/psaux/psread.h b/src/psaux/psread.h
index b0b0db8..9e21195 100644
--- a/src/psaux/psread.h
+++ b/src/psaux/psread.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2read.h                                                              */
+/*  psread.h                                                               */
 /*                                                                         */
 /*    Adobe's code for stream handling (specification).                    */
 /*                                                                         */
diff --git a/src/psaux/psstack.c b/src/psaux/psstack.c
index e97ec00..69d0633 100644
--- a/src/psaux/psstack.c
+++ b/src/psaux/psstack.c
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2stack.c                                                             */
+/*  psstack.c                                                              */
 /*                                                                         */
 /*    Adobe's code for emulating a CFF stack (body).                       */
 /*                                                                         */
diff --git a/src/psaux/psstack.h b/src/psaux/psstack.h
index ef08eef..1b9865d 100644
--- a/src/psaux/psstack.h
+++ b/src/psaux/psstack.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2stack.h                                                             */
+/*  psstack.h                                                              */
 /*                                                                         */
 /*    Adobe's code for emulating a CFF stack (specification).              */
 /*                                                                         */
diff --git a/src/psaux/pstypes.h b/src/psaux/pstypes.h
index 5b7e123..9f31493 100644
--- a/src/psaux/pstypes.h
+++ b/src/psaux/pstypes.h
@@ -1,6 +1,6 @@
 /***************************************************************************/
 /*                                                                         */
-/*  cf2types.h                                                             */
+/*  pstypes.h                                                              */
 /*                                                                         */
 /*    Adobe's code for defining data types (specification only).           */
 /*                                                                         */
diff --git a/src/type1/t1gload.c b/src/type1/t1gload.c
index e5f88d0..341d71a 100644
--- a/src/type1/t1gload.c
+++ b/src/type1/t1gload.c
@@ -39,23 +39,6 @@
 #define FT_COMPONENT  trace_t1gload
 
 
-  /*************************************************************************/
-  /*************************************************************************/
-  /*************************************************************************/
-  /**********                                                      *********/
-  /**********            COMPUTE THE MAXIMUM ADVANCE WIDTH         *********/
-  /**********                                                      *********/
-  /**********    The following code is in charge of computing      *********/
-  /**********    the maximum advance width of the font.  It        *********/
-  /**********    quickly processes each glyph charstring to        *********/
-  /**********    extract the value from either a `sbw' or `seac'   *********/
-  /**********    operator.                                         *********/
-  /**********                                                      *********/
-  /*************************************************************************/
-  /*************************************************************************/
-  /*************************************************************************/
-
-
   static FT_Error
   T1_Parse_Glyph_And_Get_Char_String( T1_Decoder  decoder,
                                       FT_UInt     glyph_index,
@@ -195,6 +178,23 @@
   }
 
 
+  /*************************************************************************/
+  /*************************************************************************/
+  /*************************************************************************/
+  /**********                                                      *********/
+  /**********            COMPUTE THE MAXIMUM ADVANCE WIDTH         *********/
+  /**********                                                      *********/
+  /**********    The following code is in charge of computing      *********/
+  /**********    the maximum advance width of the font.  It        *********/
+  /**********    quickly processes each glyph charstring to        *********/
+  /**********    extract the value from either a `sbw' or `seac'   *********/
+  /**********    operator.                                         *********/
+  /**********                                                      *********/
+  /*************************************************************************/
+  /*************************************************************************/
+  /*************************************************************************/
+
+
   FT_LOCAL_DEF( FT_Error )
   T1_Compute_Max_Advance( T1_Face  face,
                           FT_Pos*  max_advance )