[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[freetype2] API-organization f108999d6: API documentation: Re-organize c
|
From: |
Werner Lemberg |
|
Subject: |
[freetype2] API-organization f108999d6: API documentation: Re-organize chapters and sections |
|
Date: |
Mon, 24 Apr 2023 03:54:35 -0400 (EDT) |
branch: API-organization
commit f108999d6dafc79637871034ede35313ce7089c7
Author: Werner Lemberg <wl@gnu.org>
Commit: Werner Lemberg <wl@gnu.org>
API documentation: Re-organize chapters and sections
* Split the very long 'Base Interface' section into smaller sections.
* Split the 'Core API' chapter into two chapters.
* Remove single enumeration values from `@order` fields since they have no
effect.
---
include/freetype/freetype.h | 478 ++++++++++++++++++++++++++++++++++--------
include/freetype/ftchapters.h | 24 ++-
2 files changed, 419 insertions(+), 83 deletions(-)
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index efff74fe3..0faa61420 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -103,29 +103,20 @@ FT_BEGIN_HEADER
- /*************************************************************************/
- /*************************************************************************/
- /* */
- /* B A S I C T Y P E S */
- /* */
- /*************************************************************************/
- /*************************************************************************/
-
-
/**************************************************************************
*
* @section:
- * base_interface
+ * basic_handles
*
* @title:
- * Base Interface
+ * Basic Handles
*
* @abstract:
- * The FreeType~2 base font interface.
+ * The basic handles of the FreeType API.
*
* @description:
- * This section describes the most important public high-level API
- * functions of FreeType~2.
+ * This section describes the most important handles to be used with
+ * FreeType's functions.
*
* @order:
* FT_Library
@@ -133,30 +124,29 @@ FT_BEGIN_HEADER
* FT_Size
* FT_GlyphSlot
* FT_CharMap
- * FT_Encoding
- * FT_ENC_TAG
*
- * FT_FaceRec
+ */
+
+
+ /**************************************************************************
*
- * FT_FACE_FLAG_SCALABLE
- * FT_FACE_FLAG_FIXED_SIZES
- * FT_FACE_FLAG_FIXED_WIDTH
- * FT_FACE_FLAG_HORIZONTAL
- * FT_FACE_FLAG_VERTICAL
- * FT_FACE_FLAG_COLOR
- * FT_FACE_FLAG_SFNT
- * FT_FACE_FLAG_CID_KEYED
- * FT_FACE_FLAG_TRICKY
- * FT_FACE_FLAG_KERNING
- * FT_FACE_FLAG_MULTIPLE_MASTERS
- * FT_FACE_FLAG_VARIATION
- * FT_FACE_FLAG_GLYPH_NAMES
- * FT_FACE_FLAG_EXTERNAL_STREAM
- * FT_FACE_FLAG_HINTER
- * FT_FACE_FLAG_SVG
- * FT_FACE_FLAG_SBIX
- * FT_FACE_FLAG_SBIX_OVERLAY
+ * @section:
+ * test_macros
*
+ * @title:
+ * Test Macros
+ *
+ * @abstract:
+ * Macros to test various properties of fonts.
+ *
+ * @description:
+ * Macros to test the most important font properties.
+ *
+ * It is recommended to use these high-level macros instead of directly
+ * testing the corresponding flags, which are scattered over various
+ * structures.
+ *
+ * @order:
* FT_HAS_HORIZONTAL
* FT_HAS_VERTICAL
* FT_HAS_KERNING
@@ -176,21 +166,74 @@ FT_BEGIN_HEADER
* FT_IS_NAMED_INSTANCE
* FT_IS_VARIATION
*
- * FT_STYLE_FLAG_BOLD
- * FT_STYLE_FLAG_ITALIC
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ * @title:
+ * Basic Structures
*
+ * @abstract:
+ * The main structures FreeType is based on.
+ *
+ * @description:
+ * Here are the structures most of the basic handles are pointers of.
+ *
+ * @order:
+ * FT_FaceRec
* FT_SizeRec
* FT_Size_Metrics
*
+ * FT_Bitmap_Size
+ *
* FT_GlyphSlotRec
* FT_Glyph_Metrics
- * FT_SubGlyph
*
- * FT_Bitmap_Size
+ * FT_CharMapRec
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * freetype_start_and_end
+ *
+ * @title:
+ * FreeType Start and End
+ *
+ * @abstract:
+ * Functions to start and end the usage of the FreeType library.
+ *
+ * @description:
+ * Functions to start and end the usage of the FreeType library.
*
+ * @order:
* FT_Init_FreeType
* FT_Done_FreeType
*
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * font_functions
+ *
+ * @title:
+ * Font Functions
+ *
+ * @abstract:
+ * Functions to manage fonts.
+ *
+ * @description:
+ * The functions collected in this section operate on fonts globally.
+ *
+ * @order:
* FT_New_Face
* FT_Done_Face
* FT_Reference_Face
@@ -202,6 +245,29 @@ FT_BEGIN_HEADER
* FT_Attach_File
* FT_Attach_Stream
*
+ * FT_FACE_FLAG_XXX
+ * FT_STYLE_FLAG_XXX
+ * FT_OPEN_XXX
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * size_functions
+ *
+ * @title:
+ * Size Functions
+ *
+ * @abstract:
+ * Functions to manage font sizes.
+ *
+ * @description:
+ * The functions collected in this section change the size of a font
+ * globally.
+ *
+ * @order:
* FT_Set_Char_Size
* FT_Set_Pixel_Sizes
* FT_Request_Size
@@ -209,44 +275,30 @@ FT_BEGIN_HEADER
* FT_Size_Request_Type
* FT_Size_RequestRec
* FT_Size_Request
+ *
* FT_Set_Transform
* FT_Get_Transform
- * FT_Load_Glyph
- * FT_Get_Char_Index
- * FT_Get_First_Char
- * FT_Get_Next_Char
- * FT_Load_Char
*
- * FT_OPEN_MEMORY
- * FT_OPEN_STREAM
- * FT_OPEN_PATHNAME
- * FT_OPEN_DRIVER
- * FT_OPEN_PARAMS
- *
- * FT_LOAD_DEFAULT
- * FT_LOAD_RENDER
- * FT_LOAD_MONOCHROME
- * FT_LOAD_LINEAR_DESIGN
- * FT_LOAD_NO_SCALE
- * FT_LOAD_NO_HINTING
- * FT_LOAD_NO_BITMAP
- * FT_LOAD_SBITS_ONLY
- * FT_LOAD_NO_AUTOHINT
- * FT_LOAD_COLOR
- *
- * FT_LOAD_VERTICAL_LAYOUT
- * FT_LOAD_IGNORE_TRANSFORM
- * FT_LOAD_FORCE_AUTOHINT
- * FT_LOAD_NO_RECURSE
- * FT_LOAD_PEDANTIC
- *
- * FT_LOAD_TARGET_NORMAL
- * FT_LOAD_TARGET_LIGHT
- * FT_LOAD_TARGET_MONO
- * FT_LOAD_TARGET_LCD
- * FT_LOAD_TARGET_LCD_V
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_functions
*
- * FT_LOAD_TARGET_MODE
+ * @title:
+ * Glyph Functions
+ *
+ * @abstract:
+ * Functions to manage glyphs.
+ *
+ * @description:
+ * The functions collected in this section operate on single glyphs, of
+ * which @FT_Load_Glyph is most important.
+ *
+ * @order:
+ * FT_Load_Glyph
*
* FT_Render_Glyph
* FT_Render_Mode
@@ -254,34 +306,121 @@ FT_BEGIN_HEADER
* FT_Kerning_Mode
* FT_Get_Track_Kerning
*
- * FT_CharMapRec
+ * FT_LOAD_XXX
+ * FT_LOAD_TARGET_MODE
+ * FT_LOAD_TARGET_XXX
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * charmap_functions
+ *
+ * @title:
+ * CharMap Functions
+ *
+ * @abstract:
+ * Functions to manage character-to-glyph maps.
+ *
+ * @description:
+ * This section holds functions that are related to mapping character
+ * input codes to glyph indices.
+ *
+ * Note that for many scripts the simplistic approach used by FreeType
+ * of mapping a single character to a single glyph is not valid or
+ * possible! In general, a higher-level library like HarfBuzz or ICU
+ * should be used for handling text strings.
+ *
+ * @order:
* FT_Select_Charmap
* FT_Set_Charmap
* FT_Get_Charmap_Index
*
+ * FT_Get_Char_Index
+ * FT_Get_First_Char
+ * FT_Get_Next_Char
+ * FT_Load_Char
+ *
+ * FT_Encoding
+ * FT_ENC_TAG
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * information_functions
+ *
+ * @title:
+ * Information Functions
+ *
+ * @abstract:
+ * Functions to retrieve font and glyph information.
+ *
+ * @description:
+ * Functions to retrieve font and glyph information. Only some very
+ * basic data is covered; see also the chapter on the format-specific
+ * API for more.
+ *
+ *
+ * @order:
* FT_Get_Name_Index
* FT_Get_Glyph_Name
* FT_Get_Postscript_Name
* FT_Get_FSType_Flags
* FT_Get_SubGlyph_Info
*
+ * FT_SUBGLYPH_FLAG_XXX
+ * FT_FSTYPE_XXX
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ * @title:
+ * Other API Data
+ *
+ * @abstract:
+ * Other structures, enumerations, and macros.
+ *
+ * @description:
+ * Other structures, enumerations, and macros.
+ *
+ * @order:
* FT_Face_Internal
* FT_Size_Internal
* FT_Slot_Internal
*
- * FT_FACE_FLAG_XXX
- * FT_STYLE_FLAG_XXX
- * FT_OPEN_XXX
- * FT_LOAD_XXX
- * FT_LOAD_TARGET_XXX
- * FT_SUBGLYPH_FLAG_XXX
- * FT_FSTYPE_XXX
+ * FT_SubGlyph
*
* FT_HAS_FAST_GLYPHS
*
*/
+ /*************************************************************************/
+ /*************************************************************************/
+ /* */
+ /* B A S I C T Y P E S */
+ /* */
+ /*************************************************************************/
+ /*************************************************************************/
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -409,6 +548,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * basic_handles
+ *
+ */
+
/**************************************************************************
*
* @type:
@@ -483,7 +629,7 @@ FT_BEGIN_HEADER
/**************************************************************************
*
* @section:
- * base_interface
+ * basic_handles
*
*/
@@ -604,6 +750,13 @@ FT_BEGIN_HEADER
typedef struct FT_CharMapRec_* FT_CharMap;
+ /**************************************************************************
+ *
+ * @section:
+ * charmap_functions
+ *
+ */
+
/**************************************************************************
*
* @macro:
@@ -833,6 +986,13 @@ FT_BEGIN_HEADER
#define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -877,6 +1037,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ */
+
/**************************************************************************
*
* @type:
@@ -892,6 +1059,13 @@ FT_BEGIN_HEADER
typedef struct FT_Face_InternalRec_* FT_Face_Internal;
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -1128,6 +1302,13 @@ FT_BEGIN_HEADER
} FT_FaceRec;
+ /**************************************************************************
+ *
+ * @section:
+ * font_functions
+ *
+ */
+
/**************************************************************************
*
* @enum:
@@ -1272,6 +1453,13 @@ FT_BEGIN_HEADER
#define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 )
+ /**************************************************************************
+ *
+ * @section:
+ * test_macros
+ *
+ */
+
/**************************************************************************
*
* @macro:
@@ -1381,6 +1569,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES ) )
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ */
+
/**************************************************************************
*
* @macro:
@@ -1393,6 +1588,13 @@ FT_BEGIN_HEADER
#define FT_HAS_FAST_GLYPHS( face ) 0
+ /**************************************************************************
+ *
+ * @section:
+ * test_macros
+ *
+ */
+
/**************************************************************************
*
* @macro:
@@ -1628,6 +1830,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) )
+ /**************************************************************************
+ *
+ * @section:
+ * font_functions
+ *
+ */
+
/**************************************************************************
*
* @enum:
@@ -1654,6 +1863,13 @@ FT_BEGIN_HEADER
#define FT_STYLE_FLAG_BOLD ( 1 << 1 )
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ */
+
/**************************************************************************
*
* @type:
@@ -1666,6 +1882,13 @@ FT_BEGIN_HEADER
typedef struct FT_Size_InternalRec_* FT_Size_Internal;
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -1817,6 +2040,13 @@ FT_BEGIN_HEADER
} FT_SizeRec;
+ /**************************************************************************
+ *
+ * @section:
+ * other_api_data
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -1848,6 +2078,13 @@ FT_BEGIN_HEADER
typedef struct FT_Slot_InternalRec_* FT_Slot_Internal;
+ /**************************************************************************
+ *
+ * @section:
+ * basic_structures
+ *
+ */
+
/**************************************************************************
*
* @struct:
@@ -2092,6 +2329,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * freetype_start_and_end
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -2149,6 +2393,13 @@ FT_BEGIN_HEADER
FT_Done_FreeType( FT_Library library );
+ /**************************************************************************
+ *
+ * @section:
+ * font_functions
+ *
+ */
+
/**************************************************************************
*
* @enum:
@@ -2650,6 +2901,13 @@ FT_BEGIN_HEADER
FT_Done_Face( FT_Face face );
+ /**************************************************************************
+ *
+ * @section:
+ * size_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -2942,6 +3200,13 @@ FT_BEGIN_HEADER
FT_UInt pixel_height );
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -2990,6 +3255,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags );
+ /**************************************************************************
+ *
+ * @section:
+ * charmap_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -3033,6 +3305,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags );
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_functions
+ *
+ */
+
/**************************************************************************
*
* @enum:
@@ -3372,6 +3651,13 @@ FT_BEGIN_HEADER
FT_STATIC_CAST( FT_Render_Mode, ( (x) >> 16 ) & 15 )
+ /**************************************************************************
+ *
+ * @section:
+ * size_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -3447,6 +3733,13 @@ FT_BEGIN_HEADER
FT_Vector* delta );
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_functions
+ *
+ */
+
/**************************************************************************
*
* @enum:
@@ -3841,6 +4134,13 @@ FT_BEGIN_HEADER
FT_Fixed* akerning );
+ /**************************************************************************
+ *
+ * @section:
+ * charmap_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -4057,6 +4357,13 @@ FT_BEGIN_HEADER
FT_UInt *agindex );
+ /**************************************************************************
+ *
+ * @section:
+ * font_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
@@ -4155,6 +4462,13 @@ FT_BEGIN_HEADER
FT_Parameter* properties );
+ /**************************************************************************
+ *
+ * @section:
+ * information_functions
+ *
+ */
+
/**************************************************************************
*
* @function:
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 6a9733ad7..16ea66742 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -33,7 +33,29 @@
* @sections:
* version
* basic_types
- * base_interface
+ * basic_handles
+ * test_macros
+ * basic_structures
+ * freetype_start_and_end
+ * font_functions
+ * size_functions
+ * glyph_functions
+ * charmap_functions
+ * information_functions
+ * other_api_data
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * @chapter:
+ * extended_api
+ *
+ * @title:
+ * Extended API
+ *
+ * @sections:
* glyph_variants
* color_management
* layer_management
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [freetype2] API-organization f108999d6: API documentation: Re-organize chapters and sections,
Werner Lemberg <=