Improve documentation of built-in fonts and their handling

8 files changed, 147 insertions, 53 deletions

diff --git a/docs/naturaldocs/project/Menu.txt b/docs/naturaldocs/project/Menu.txt
index d4e9f41..f12369e 100644
--- a/docs/naturaldocs/project/Menu.txt
+++ b/docs/naturaldocs/project/Menu.txt
@@ -46,23 +46,23 @@ Format: 1.52
 # --------------------------------------------------------------------------
 
 
-File: About LibGD 2.3.0-dev  (preamble.txt)
+File: About LibGD 2.3.0-dev  (no auto-title, preamble.txt)
 
 Group: Image Formats  {
 
-   File: BMP IO  (gd_bmp.c)
-   File: GD IO  (gd_gd.c)
-   File: GD2 IO  (gd_gd2.c)
-   File: GIF Input  (gd_gif_in.c)
-   File: GIF Output  (gd_gif_out.c)
-   File: JPEG IO  (gd_jpeg.c)
-   File: PNG IO  (gd_png.c)
-   File: TGA Input  (gd_tga.c)
-   File: TIFF IO  (gd_tiff.c)
-   File: WBMP IO  (gd_wbmp.c)
-   File: WebP IO  (gd_webp.c)
-   File: XBM IO  (gd_xbm.c)
-   File: XPM Input  (gdxpm.c)
+   File: BMP IO  (no auto-title, gd_bmp.c)
+   File: GD IO  (no auto-title, gd_gd.c)
+   File: GD2 IO  (no auto-title, gd_gd2.c)
+   File: GIF Input  (no auto-title, gd_gif_in.c)
+   File: GIF Output  (no auto-title, gd_gif_out.c)
+   File: JPEG IO  (no auto-title, gd_jpeg.c)
+   File: PNG IO  (no auto-title, gd_png.c)
+   File: TGA Input  (no auto-title, gd_tga.c)
+   File: TIFF IO  (no auto-title, gd_tiff.c)
+   File: WBMP IO  (no auto-title, gd_wbmp.c)
+   File: WebP IO  (no auto-title, gd_webp.c)
+   File: XBM IO  (no auto-title, gd_xbm.c)
+   File: XPM Input  (no auto-title, gdxpm.c)
    }  # Group: Image Formats
 
 File: gd.c  (gd.c)
@@ -78,11 +78,6 @@ File: gd_topal.c  (gd_topal.c)
 File: gd_transform.c  (gd_transform.c)
 File: gd_version.c  (gd_version.c)
 File: gdColorMapLookup  (gd_color_map.c)
-File: gdFontGetGiant  (gdfontg.c)
-File: gdFontGetLarge  (gdfontl.c)
-File: gdFontGetMediumBold  (gdfontmb.c)
-File: gdFontGetSmall  (gdfonts.c)
-File: gdFontGetTiny  (gdfontt.c)
 File: gdFree  (gdhelpers.c)
 File: gdft.c  (gdft.c)
 File: gdfx.c  (gdfx.c)
@@ -93,6 +88,15 @@ File: gdNewSSCtx  (gd_io_ss.c)
 File: License  (license.txt)
 File: Matrix  (gd_matrix.c)
 
+Group: Built-in Fonts  {
+
+   File: Giant Font  (no auto-title, gdfontg.c)
+   File: Large Font  (no auto-title, gdfontl.c)
+   File: Medium Bold Font  (no auto-title, gdfontmb.c)
+   File: Small Font  (no auto-title, gdfonts.c)
+   File: Tiny Font  (no auto-title, gdfontt.c)
+   }  # Group: Built-in Fonts
+
 Group: Index  {
 
    Constant Index: Constants
diff --git a/src/gd.c b/src/gd.c
index 9fe175f..7b481b9 100644
--- a/src/gd.c
+++ b/src/gd.c
@@ -1686,9 +1686,25 @@ BGD_DECLARE(int) gdImageBoundsSafe (gdImagePtr im, int x, int y)
 	return gdImageBoundsSafeMacro (im, x, y);
 }
 
-/*
-	Function: gdImageChar
-*/
+/**
+ * Function: gdImageChar
+ *
+ * Draws a single character.
+ *
+ * Parameters:
+ *  im    - The image to draw onto.
+ *  f     - The raster font.
+ *  x     - The x coordinate of the upper left pixel.
+ *  y     - The y coordinate of the upper left pixel.
+ *  c     - The character.
+ *  color - The color.
+ *
+ * Variants:
+ *  - <gdImageCharUp>
+ *
+ * See also:
+ *  - <gdFontPtr>
+ */
 BGD_DECLARE(void) gdImageChar (gdImagePtr im, gdFontPtr f, int x, int y, int c, int color)
 {
 	int cx, cy;
@@ -1715,9 +1731,9 @@ BGD_DECLARE(void) gdImageChar (gdImagePtr im, gdFontPtr f, int x, int y, int c,
 	}
 }
 
-/*
-	Function: gdImageCharUp
-*/
+/**
+ * Function: gdImageCharUp
+ */
 BGD_DECLARE(void) gdImageCharUp (gdImagePtr im, gdFontPtr f, int x, int y, int c, int color)
 {
 	int cx, cy;
@@ -1744,9 +1760,28 @@ BGD_DECLARE(void) gdImageCharUp (gdImagePtr im, gdFontPtr f, int x, int y, int c
 	}
 }
 
-/*
-	Function: gdImageString
-*/
+/**
+ * Function: gdImageString
+ * 
+ * Draws a character string.
+ *
+ * Parameters:
+ *  im    - The image to draw onto.
+ *  f     - The raster font.
+ *  x     - The x coordinate of the upper left pixel.
+ *  y     - The y coordinate of the upper left pixel.
+ *  c     - The character string.
+ *  color - The color.
+ *
+ * Variants:
+ *  - <gdImageStringUp>
+ *  - <gdImageString16>
+ *  - <gdImageStringUp16>
+ *
+ * See also:
+ *  - <gdFontPtr>
+ *  - <gdImageStringTTF>
+ */
 BGD_DECLARE(void) gdImageString (gdImagePtr im, gdFontPtr f,
 								 int x, int y, unsigned char *s, int color)
 {
@@ -1759,9 +1794,9 @@ BGD_DECLARE(void) gdImageString (gdImagePtr im, gdFontPtr f,
 	}
 }
 
-/*
-	Function: gdImageStringUp
-*/
+/**
+ * Function: gdImageStringUp
+ */
 BGD_DECLARE(void) gdImageStringUp (gdImagePtr im, gdFontPtr f,
 								   int x, int y, unsigned char *s, int color)
 {
@@ -1776,9 +1811,9 @@ BGD_DECLARE(void) gdImageStringUp (gdImagePtr im, gdFontPtr f,
 
 static int strlen16 (unsigned short *s);
 
-/*
-	Function: gdImageString16
-*/
+/**
+ * Function: gdImageString16
+ */
 BGD_DECLARE(void) gdImageString16 (gdImagePtr im, gdFontPtr f,
 								   int x, int y, unsigned short *s, int color)
 {
@@ -1791,9 +1826,9 @@ BGD_DECLARE(void) gdImageString16 (gdImagePtr im, gdFontPtr f,
 	}
 }
 
-/*
-	Function: gdImageStringUp16
-*/
+/**
+ * Function: gdImageStringUp16
+ */
 BGD_DECLARE(void) gdImageStringUp16 (gdImagePtr im, gdFontPtr f,
 									 int x, int y, unsigned short *s, int color)
 {
diff --git a/src/gd.h b/src/gd.h
index 04cad83..5bfa3e8 100644
--- a/src/gd.h
+++ b/src/gd.h
@@ -401,7 +401,7 @@ gdPointF, *gdPointFPtr;
   A font structure, containing the bitmaps of all characters in a
   font.  Used to declare the characteristics of a font. Text-output
   functions expect these as their second argument, following the
-  <gdImagePtr> argument.  <gdFontSmall> and <gdFontGetLarge> both
+  <gdImagePtr> argument.  <gdFontGetSmall> and <gdFontGetLarge> both
   return one.
 
   You can provide your own font data by providing such a structure and
diff --git a/src/gdfontg.c b/src/gdfontg.c
index 04f3362..2adf6da 100644
--- a/src/gdfontg.c
+++ b/src/gdfontg.c
@@ -10,6 +10,15 @@
    "Libor Skarvada, libor@informatics.muni.cz"
  */
 
+/**
+ * File: Giant Font
+ *
+ * A very large ISO-8859-2 raster font (9x15 pixels).
+ *
+ * The font is supposed to be used with <gdImageChar> and <gdImageString>
+ * and their variants.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -4382,9 +4391,11 @@ gdFont gdFontGiantRep = {
 
 BGD_EXPORT_DATA_PROT gdFontPtr gdFontGiant = &gdFontGiantRep;
 
-/*
-	Function: gdFontGetGiant
-*/
+/**
+ * Function: gdFontGetGiant
+ *
+ * Returns the built-in giant font.
+ */
 BGD_DECLARE(gdFontPtr) gdFontGetGiant (void)
 {
 	return gdFontGiant;
diff --git a/src/gdfontl.c b/src/gdfontl.c
index 8501b5f..97f7a65 100644
--- a/src/gdfontl.c
+++ b/src/gdfontl.c
@@ -11,6 +11,15 @@
    "Libor Skarvada, libor@informatics.muni.cz"
  */
 
+/**
+ * File: Large Font
+ *
+ * A large ISO-8859-2 raster font (8x16 pixels).
+ *
+ * The font is supposed to be used with <gdImageChar> and <gdImageString>
+ * and their variants.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -4639,9 +4648,11 @@ gdFont gdFontLargeRep = {
 
 BGD_EXPORT_DATA_PROT gdFontPtr gdFontLarge = &gdFontLargeRep;
 
-/*
-	Function: gdFontGetLarge
-*/
+/**
+ * Function: gdFontGetLarge
+ *
+ * Returns the built-in large font.
+ */
 BGD_DECLARE(gdFontPtr)
 gdFontGetLarge (void)
 {
diff --git a/src/gdfontmb.c b/src/gdfontmb.c
index 566cc6d..debee4e 100644
--- a/src/gdfontmb.c
+++ b/src/gdfontmb.c
@@ -9,6 +9,15 @@
    No copyright info was found in the original bdf.
  */
 
+/**
+ * File: Medium Bold Font
+ *
+ * A medium bold ISO-8859-2 raster font (7x13 pixels).
+ *
+ * The font is supposed to be used with <gdImageChar> and <gdImageString>
+ * and their variants.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -3869,9 +3878,11 @@ gdFont gdFontMediumBoldRep = {
 
 BGD_EXPORT_DATA_PROT gdFontPtr gdFontMediumBold = &gdFontMediumBoldRep;
 
-/*
-	Function: gdFontGetMediumBold
-*/
+/**
+ * Function: gdFontGetMediumBold
+ *
+ * Returns the built-in medium bold font.
+ */
 BGD_DECLARE(gdFontPtr)
 gdFontGetMediumBold (void)
 {
diff --git a/src/gdfonts.c b/src/gdfonts.c
index f84b2ee..e184e36 100644
--- a/src/gdfonts.c
+++ b/src/gdfonts.c
@@ -7,6 +7,15 @@
    No copyright info was found in the original bdf.
  */
 
+/**
+ * File: Small Font
+ *
+ * A small ISO-8859-2 raster font (7x13 pixels).
+ *
+ * The font is supposed to be used with <gdImageChar> and <gdImageString>
+ * and their variants.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -3867,9 +3876,11 @@ gdFont gdFontSmallRep = {
 
 BGD_EXPORT_DATA_PROT gdFontPtr gdFontSmall = &gdFontSmallRep;
 
-/*
-	Function: gdFontGetSmall
-*/
+/**
+ * Function: gdFontGetSmall
+ *
+ * Returns the built-in small font.
+ */
 BGD_DECLARE(gdFontPtr)
 gdFontGetSmall (void)
 {
diff --git a/src/gdfontt.c b/src/gdfontt.c
index 3c97c4d..e7bb345 100644
--- a/src/gdfontt.c
+++ b/src/gdfontt.c
@@ -10,6 +10,15 @@
    "Libor Skarvada, libor@informatics.muni.cz"
  */
 
+/**
+ * File: Tiny Font
+ *
+ * A very small ISO-8859-2 raster font (5x8 pixels).
+ *
+ * The font is supposed to be used with <gdImageChar> and <gdImageString>
+ * and their variants.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -2590,9 +2599,11 @@ gdFont gdFontTinyRep = {
 
 BGD_EXPORT_DATA_PROT gdFontPtr gdFontTiny = &gdFontTinyRep;
 
-/*
-	Function: gdFontGetTiny
-*/
+/**
+ * Function: gdFontGetTiny
+ *
+ * Returns the built-in tiny font.
+ */
 BGD_DECLARE(gdFontPtr)
 gdFontGetTiny (void)
 {