Commit 4091786c8110f56a45ea7cc7156730bd73dbdeee

Werner Lemberg 2006-04-01T18:49:07

Formatting.

diff --git a/ChangeLog b/ChangeLog
index e60fd6a..6921afb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,9 @@
-2006-04-01  David Turner   <david@freetype.org>
+2006-04-01  David Turner  <david@freetype.org>
 
-       * docs/CHANGES: update
+	* docs/CHANGES: Updated.
 
-       * include/freetype/ftcache.h, include/freetype/config/ftheader.h:
-       updating documentation comments
+	* include/freetype/ftcache.h, include/freetype/config/ftheader.h:
+	Update documentation comments.
 
 2006-04-01  Werner Lemberg  <wl@gnu.org>
 
diff --git a/docs/CHANGES b/docs/CHANGES
index f86b520..7b1146f 100644
--- a/docs/CHANGES
+++ b/docs/CHANGES
@@ -42,8 +42,8 @@ LATEST CHANGES BETWEEN 2.2 and 2.1.10
 
     - The  LIGHT  hinting algorithm  produces  more pleasant  results.
       Also, using the  FT_LOAD_TARGET_LIGHT flags within FT_Load_Glyph
-      always forces auto-hinting, as a special exception. This allows
-      you to experiment with it even if you have enabled the TrueType
+      always forces auto-hinting, as a special exception.  This allows
+      you to experiment with it  even if you have enabled the TrueType
       bytecode interpreter in your build.
 
     - The auto hinter now employs a new algorithm for CJK fonts, based
@@ -77,7 +77,7 @@ LATEST CHANGES BETWEEN 2.2 and 2.1.10
       bitmap strikes should be updated to use this function.
 
     - A  new API  `FT_Get_SubGlyph_Info'  has been  added to  retrieve
-      subglyph data. This can be used by rogue clients which used to
+      subglyph data.  This can be  used by rogue clients which used to
       access the internal headers to get the corresponding data.
 
     - In 2.1.10, the behaviour of `FT_Set_Pixel_Sizes' was changed for
diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h
index 4cfa060..f300ec6 100644
--- a/include/freetype/config/ftheader.h
+++ b/include/freetype/config/ftheader.h
@@ -623,9 +623,9 @@
    *
    * @description:
    *   A macro used in #include statements to name the file containing the
-   *   FreeType 2 API used to stroke outline path
+   *   FreeType 2 API used to stroke outline path.
    */
-#define FT_STROKER_H            <freetype/ftstroke.h>
+#define FT_STROKER_H  <freetype/ftstroke.h>
 
 
   /*************************************************************************
@@ -635,9 +635,9 @@
    *
    * @description:
    *   A macro used in #include statements to name the file containing the
-   *   FreeType 2 API used to perform artificial obliquing and emboldening
+   *   FreeType 2 API used to perform artificial obliquing and emboldening.
    */
-#define FT_SYNTHESIS_H          <freetype/ftsynth.h>
+#define FT_SYNTHESIS_H  <freetype/ftsynth.h>
 
 
   /*************************************************************************
@@ -648,9 +648,9 @@
    * @description:
    *   A macro used in #include statements to name the file containing the
    *   FreeType 2 API used to provide functions specific to the XFree86 and
-   *   X.Org X11 servers
+   *   X.Org X11 servers.
    */
-#define FT_XFREE86_H              <freetype/ftxf86.h>
+#define FT_XFREE86_H  <freetype/ftxf86.h>
 
 
   /*************************************************************************
@@ -660,10 +660,10 @@
    *
    * @description:
    *   A macro used in #include statements to name the file containing the
-   *   FreeType 2 API used to perform trigonometric computations (e.g.
+   *   FreeType 2 API used to perform trigonometric computations (e.g.,
    *   cosines and arc tangents).
    */
-#define FT_TRIGONOMETRY_H       <freetype/fttrigon.h>
+#define FT_TRIGONOMETRY_H  <freetype/fttrigon.h>
 
   /* */
 
diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h
index 2cd1957..c63b2b2 100644
--- a/include/freetype/ftcache.h
+++ b/include/freetype/ftcache.h
@@ -46,38 +46,39 @@ FT_BEGIN_HEADER
    *
    *   Note that all types and functions begin with the FTC_ prefix.
    *
-   *   the cache is highly portable and thus doesn't know anything about
-   *   the fonts installed on your system, or how to access them. This implies
+   *   The cache is highly portable and thus doesn't know anything about the
+   *   fonts installed on your system, or how to access them.  This implies
    *   the following scheme:
    *
-   *   first, available/installed font faces are uniquely identified by
-   *   @FTC_FaceID values provided to the cache by the client. Note that the
-   *   cache only stores and compares these values, and doesn't try to
+   *   First, available or installed font faces are uniquely identified by
+   *   @FTC_FaceID values, provided to the cache by the client.  Note that
+   *   the cache only stores and compares these values, and doesn't try to
    *   interpret them in any way.
    *
-   *   Second, the cache will call, only when needed, a client-provided
-   *   function to convert a @FTC_FaceID into a new @FT_Face object. The latter
-   *   will then be completely managed by the cache, including its termination
+   *   Second, the cache calls, only when needed, a client-provided function
+   *   to convert a @FTC_FaceID into a new @FT_Face object.  The latter is
+   *   then completely managed by the cache, including its termination
    *   through @FT_Done_Face.
    *
-   *   Clients are free to map face ids to anything. The most simple usage is
-   *   to associate them to a (pathname,face_index) pair that is used to call
-   *   @FT_New_Face. However, more complex schemes are also possible.
+   *   Clients are free to map face IDs to anything else.  The most simple
+   *   usage is to associate them to a (pathname,face_index) pair that is
+   *   used to call @FT_New_Face.  However, more complex schemes are also
+   *   possible.
    *
-   *   Note that for the cache to work correctly, the face id values must be
-   *   *persistent*, which means that the content they point to should not
+   *   Note that for the cache to work correctly, the face ID values must be
+   *   *persistent*, which means that the contents they point to should not
    *   change at runtime, or that their value should not become invalid.
    *
-   *   If this is unavoidable (e.g. when a font is uninstalled at runtime),
+   *   If this is unavoidable (e.g., when a font is uninstalled at runtime),
    *   you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
    *   the cache get rid of any references to the old @FTC_FaceID it may
-   *   keep internally. Failure to do so will lead to incorrect behaviour
+   *   keep internally.  Failure to do so will lead to incorrect behaviour
    *   or even crashes.
    *
-   *   To use the cache, start by calling @FTC_Manager_New to create a new
-   *   @FTC_Manager object, which models a single cache instance. You can
-   *   then lookup @FT_Face and @FT_Size objects with @FTC_Manager_LookupFace
-   *   and @FTC_Manager_LookupSize respectively.
+   *   To use the cache, start with calling @FTC_Manager_New to create a new
+   *   @FTC_Manager object, which models a single cache instance.  You can
+   *   then look up @FT_Face and @FT_Size objects with
+   *   @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
    *
    *   If you want to use the charmap caching, call @FTC_CMapCache_New, then
    *   later use @FTC_CMapCache_Lookup to perform the equivalent of
@@ -87,14 +88,13 @@ FT_BEGIN_HEADER
    *   later use @FTC_ImageCache_Lookup to retrieve the corresponding
    *   @FT_Glyph objects from the cache.
    *
-   *   If you need lots of small bitmaps, it is much more memory efficient to
-   *   call @FTC_SBitCache_New, then later @FTC_SBitCache_Lookup, this returns
-   *   @FTC_SBitRec structures, which are used to store small bitmaps directly.
-   *   (a small bitmap is one whose metrics and dimensions all fit in 8-bit
-   *   integers).
+   *   If you need lots of small bitmaps, it is much more memory efficient
+   *   to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup.  This
+   *   returns @FTC_SBitRec structures, which are used to store small
+   *   bitmaps directly.  (A small bitmap is one whose metrics and
+   *   dimensions all fit into 8-bit integers).
    *
-   *   We hope to also provide a kerning cache in the near future. Stay
-   *   tuned.
+   *   We hope to also provide a kerning cache in the near future.
    *
    *
    * <Order>
@@ -139,65 +139,70 @@ FT_BEGIN_HEADER
   /*************************************************************************/
 
 
- /*************************************************************************
-  *
-  * @type: FTC_FaceID
-  *
-  * @description:
-  *    An opaque pointer type that is used to identity face objects.  The
-  *    contents of such objects is application-dependent.
-  *
-  *    these pointers are typically used to point to a user-defined
-  *    structure containing a font file path, and face index.
-  *
-  * @note:
-  *    never use NULL as a valid @FTC_FaceID
-  *
-  *    Face ids are passed by the client to the cache manager, which will
-  *    call, when needed, the @FTC_Face_Requester to translate them into
-  *    new @FT_Face objects
-  *
-  *    if the content of a given face id changes at runtime, or if the
-  *    value becomes invalid (e.g. when uninstalling a font), you should
-  *    immediately call @FTC_Manager_RemoveFaceID before any other cache
-  *    function.
-  *
-  *    Failure to do so will result in incorrect behaviour or even
-  *    memory leaks and crashes !
-  **/
+  /*************************************************************************
+   *
+   * @type: FTC_FaceID
+   *
+   * @description:
+   *   An opaque pointer type that is used to identity face objects.  The
+   *   contents of such objects is application-dependent.
+   *
+   *   These pointers are typically used to point to a user-defined
+   *   structure containing a font file path, and face index.
+   *
+   * @note:
+   *   Never use NULL as a valid @FTC_FaceID.
+   *
+   *   Face IDs are passed by the client to the cache manager, which calls,
+   *   when needed, the @FTC_Face_Requester to translate them into new
+   *   @FT_Face objects.
+   *
+   *   If the content of a given face ID changes at runtime, or if the value
+   *   becomes invalid (e.g., when uninstalling a font), you should
+   *   immediately call @FTC_Manager_RemoveFaceID before any other cache
+   *   function.
+   *
+   *   Failure to do so will result in incorrect behaviour or even
+   *   memory leaks and crashes.
+   */
   typedef struct FTC_FaceIDRec_*  FTC_FaceID;
 
 
- /************************************************************************
-  *
-  * @functype: FTC_Face_Requester
-  *
-  * @description:
-  *    A callback function provided by client applications.  It is used
-  *    by the cache manager to translate a given @FTC_FaceID into a new
-  *    valid @FT_Face object, on demand.
-  *
-  * <Input>
-  *    face_id  :: The face ID to resolve.
-  *
-  *    library  :: A handle to a FreeType library object.
-  *
-  *    req_data :: Application-provided request data (see note below).
-  *
-  * <Output>
-  *    aface   :: A new @FT_Face handle.
-  *
-  * <Return>
-  *    FreeType error code.  0 means success.
-  *
-  * <Note>
-  *    The third parameter 'req_data' is the same than the one passed
-  *    by the client when @FTC_Manager_New is called.
-  *
-  *    The face requester should not perform funny things on the returned
-  *    face object, like creating a new @FT_Size for it, or setting a
-  *    transformation through @FT_Set_Transform!
-  **/
+  /************************************************************************
+   *
+   * @functype:
+   *   FTC_Face_Requester
+   *
+   * @description:
+   *   A callback function provided by client applications.  It is used by
+   *   the cache manager to translate a given @FTC_FaceID into a new valid
+   *   @FT_Face object, on demand.
+   *
+   * <Input>
+   *   face_id ::
+   *     The face ID to resolve.
+   *
+   *   library ::
+   *     A handle to a FreeType library object.
+   *
+   *   req_data ::
+   *     Application-provided request data (see note below).
+   *
+   * <Output>
+   *   aface ::
+   *     A new @FT_Face handle.
+   *
+   * <Return>
+   *   FreeType error code.  0 means success.
+   *
+   * <Note>
+   *   The third parameter `req_data' is the same as the one passed by the
+   *   client when @FTC_Manager_New is called.
+   *
+   *   The face requester should not perform funny things on the returned
+   *   face object, like creating a new @FT_Size for it, or setting a
+   *   transformation through @FT_Set_Transform!
+   */
   typedef FT_Error
   (*FTC_Face_Requester)( FTC_FaceID  face_id,
                          FT_Library  library,
@@ -234,12 +239,12 @@ FT_BEGIN_HEADER
   /*    It is used to cache one or more @FT_Face objects, along with       */
   /*    corresponding @FT_Size objects.                                    */
   /*                                                                       */
-  /*    the manager intentionally limits the total number of opened        */
-  /*    @FT_Face and @FT_Size objects to limit memory usage. See the       */
-  /*    'max_faces' and 'max_sizes' parameters of @FTC_Manager_New.        */
+  /*    The manager intentionally limits the total number of opened        */
+  /*    @FT_Face and @FT_Size objects to control memory usage.  See the    */
+  /*    `max_faces' and `max_sizes' parameters of @FTC_Manager_New.        */
   /*                                                                       */
-  /*    the manager is also used to cache 'nodes' of various types         */
-  /*    while limiting their total memory usage.                           */
+  /*    The manager is also used to cache `nodes' of various types while   */
+  /*    limiting their total memory usage.                                 */
   /*                                                                       */
   /*    All limitations are enforced by keeping lists of managed objects   */
   /*    in most-recently-used order, and flushing old nodes to make room   */
@@ -277,24 +282,23 @@ FT_BEGIN_HEADER
   /*    Creates a new cache manager.                                       */
   /*                                                                       */
   /* <Input>                                                               */
-  /*    library     :: The parent FreeType library handle to use.          */
+  /*    library   :: The parent FreeType library handle to use.            */
   /*                                                                       */
-  /*    max_faces   :: Maximum number of opened @FT_Face objects managed   */
-  /*                   by this cache instance.                             */
+  /*    max_faces :: Maximum number of opened @FT_Face objects managed by  */
+  /*                 this cache instance.                                  */
   /*                                                                       */
-  /*    max_sizes   :: Maximum number of opened @FT_Size objects managed   */
-  /*                   by this cache instance.                             */
+  /*    max_sizes :: Maximum number of opened @FT_Size objects managed by  */
+  /*                 this cache instance.                                  */
   /*                                                                       */
-  /*    max_bytes   :: Maximum number of bytes to use for cached data      */
-  /*                   nodes.  Use 0 for defaults.  Note that this value   */
-  /*                   does not account for managed FT_Face and FT_Size    */
-  /*                   objects.                                            */
+  /*    max_bytes :: Maximum number of bytes to use for cached data nodes. */
+  /*                 Use 0 for defaults.  Note that this value does not    */
+  /*                 account for managed FT_Face and FT_Size objects.      */
   /*                                                                       */
-  /*    requester   :: An application-provided callback used to translate  */
-  /*                   face IDs into real @FT_Face objects.                */
+  /*    requester :: An application-provided callback used to translate    */
+  /*                 face IDs into real @FT_Face objects.                  */
   /*                                                                       */
-  /*    req_data    :: A generic pointer that is passed to the requester   */
-  /*                   each time it is called (see @FTC_Face_Requester).   */
+  /*    req_data  :: A generic pointer that is passed to the requester     */
+  /*                 each time it is called (see @FTC_Face_Requester).     */
   /*                                                                       */
   /* <Output>                                                              */
   /*    amanager  :: A handle to a new manager object.  0 in case of       */
@@ -376,7 +380,6 @@ FT_BEGIN_HEADER
   /*    the @FT_Set_Transform function) on a returned face!  If you need   */
   /*    to transform glyphs, do it yourself after glyph loading.           */
   /*                                                                       */
-  /* <Note>                                                                */
   /*    When you perform a lookup, out-of-memory errors are detected       */
   /*    _within_ the lookup and force incremental flushes of the cache     */
   /*    until enough memory is released for the lookup to succeed.         */