Doc fix.

2 files changed, 67 insertions, 55 deletions

diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h
index 43585bc5c..f3198111c 100644
--- a/include/freetype/fterrors.h
+++ b/include/freetype/fterrors.h
@@ -19,82 +19,90 @@
   /**************************************************************************
    *
    * @section:
-   *  error_enumerations
+   *   error_enumerations
    *
    * @title:
-   *  Error Enumerations
+   *   Error Enumerations
    *
    * @abstract:
-   *  How to handle errors and error strings.
+   *   How to handle errors and error strings.
    *
    * @description:
-   *  The header file `fterrors.h` (which is automatically included by
-   *  `freetype.h` defines the handling of FreeType's enumeration constants.
-   *  It can also be used to generate error message strings with a small
-   *  macro trick explained below.
+   *   The header file `fterrors.h` (which is automatically included by
+   *   `freetype.h` defines the handling of FreeType's enumeration
+   *   constants.  It can also be used to generate error message strings
+   *   with a small macro trick explained below.
    *
-   *  **Error Formats**
+   *   **Error Formats**
    *
-   *  The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be
-   *  defined in `ftoption.h` in order to make the higher byte indicate the
-   *  module where the error has happened (this is not compatible with
-   *  standard builds of FreeType~2, however).  See the file `ftmoderr.h` for
-   *  more details.
+   *   The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be
+   *   defined in `ftoption.h` in order to make the higher byte indicate the
+   *   module where the error has happened (this is not compatible with
+   *   standard builds of FreeType~2, however).  See the file `ftmoderr.h`
+   *   for more details.
    *
-   *  **Error Message Strings**
+   *   **Error Message Strings**
    *
-   *  Error definitions are set up with special macros that allow client
-   *  applications to build a table of error message strings.  The strings
-   *  are not included in a normal build of FreeType~2 to save space (most
-   *  client applications do not use them).
+   *   Error definitions are set up with special macros that allow client
+   *   applications to build a table of error message strings.  The strings
+   *   are not included in a normal build of FreeType~2 to save space (most
+   *   client applications do not use them).
    *
-   *  To do so, you have to define the following macros before including this
-   *  file.
+   *   To do so, you have to define the following macros before including
+   *   this file.
    *
-   *  ```
-   *    FT_ERROR_START_LIST
-   *  ```
+   *   ```
+   *     FT_ERROR_START_LIST
+   *   ```
    *
-   *  This macro is called before anything else to define the start of the
-   *  error list.  It is followed by several FT_ERROR_DEF calls.
+   *   This macro is called before anything else to define the start of the
+   *   error list.  It is followed by several FT_ERROR_DEF calls.
    *
-   *  ```
-   *    FT_ERROR_DEF( e, v, s )
-   *  ```
+   *   ```
+   *     FT_ERROR_DEF( e, v, s )
+   *   ```
    *
-   *  This macro is called to define one single error.  'e' is the error code
-   *  identifier (e.g., `Invalid_Argument`), 'v' is the error's numerical
-   *  value, and 's' is the corresponding error string.
+   *   This macro is called to define one single error.  'e' is the error
+   *   code identifier (e.g., `Invalid_Argument`), 'v' is the error's
+   *   numerical value, and 's' is the corresponding error string.
    *
-   *  ```
-   *    FT_ERROR_END_LIST
-   *  ```
+   *   ```
+   *     FT_ERROR_END_LIST
+   *   ```
    *
-   *  This macro ends the list.
+   *   This macro ends the list.
    *
-   *  Additionally, you have to undefine `FTERRORS_H_` before #including this
-   *  file.
+   *   Additionally, you have to undefine `FTERRORS_H_` before #including
+   *   this file.
    *
-   *  Here is a simple example.
+   *   Here is a simple example.
    *
-   *  ```
-   *    #undef FTERRORS_H_
-   *    #define FT_ERRORDEF( e, v, s )  { e, s },
-   *    #define FT_ERROR_START_LIST     {
-   *    #define FT_ERROR_END_LIST       { 0, NULL } };
+   *   ```
+   *     #undef FTERRORS_H_
+   *     #define FT_ERRORDEF( e, v, s )  { e, s },
+   *     #define FT_ERROR_START_LIST     {
+   *     #define FT_ERROR_END_LIST       { 0, NULL } };
    *
-   *    const struct
-   *    {
-   *      int          err_code;
-   *      const char*  err_msg;
-   *    } ft_errors[] =
+   *     const struct
+   *     {
+   *       int          err_code;
+   *       const char*  err_msg;
+   *     } ft_errors[] =
    *
-   *    #include FT_ERRORS_H
-   *  ```
+   *     #include FT_ERRORS_H
+   *   ```
    *
-   *  Note that `FT_Err_Ok` is _not_ defined with `FT_ERRORDEF`; it is
-   *  always zero.
+   *   An alternative to using an array is a switch statement.
    *
+   *   ```
+   *     #undef FTERRORS_H_
+   *     #define FT_ERROR_START_LIST     switch ( error_code ) {
+   *     #define FT_ERRORDEF( e, v, s )    case v: return s;
+   *     #define FT_ERROR_END_LIST       }
+   *   ```
+   *
+   *   If you use FT_CONFIG_OPTION_USE_MODULE_ERRORS, 'error_code' should be
+   *   replaced with 'FT_ERROR_BASE(error_code)' in the last example.
    */
 
   /* */
diff --git a/include/freetype/ftmoderr.h b/include/freetype/ftmoderr.h
index af651c225..e72933ac8 100644
--- a/include/freetype/ftmoderr.h
+++ b/include/freetype/ftmoderr.h
@@ -37,6 +37,7 @@
    * provides some macros in `fttypes.h`.
    *
    *   FT_ERR( err )
+   *
    *     Add current error module prefix (as defined with the `FT_ERR_PREFIX`
    *     macro) to 'err'.  For example, in the BDF module the line
    *
@@ -49,7 +50,9 @@
    *     For simplicity, you can always use `FT_Err_Ok` directly instead of
    *     'FT_ERR( Ok )'.
    *
-   *   FT_ERR_EQ( errcode, err ) FT_ERR_NEQ( errcode, err )
+   *   FT_ERR_EQ( errcode, err )
+   *   FT_ERR_NEQ( errcode, err )
+   *
    *     Compare error code 'errcode' with the error 'err' for equality and
    *     inequality, respectively.  Example:
    *
@@ -63,9 +66,10 @@
    *       if ( error == FT_Err_Invalid_Outline )
    *         ...
    *
-   *   FT_ERROR_BASE( errcode ) FT_ERROR_MODULE( errcode )
-   *     Get base error and module error code, respectively.
+   *   FT_ERROR_BASE( errcode )
+   *   FT_ERROR_MODULE( errcode )
    *
+   *     Get base error and module error code, respectively.
    *
    * It can also be used to create a module error message table easily with
    * something like