Started importing the old manual into Naturaldocs comments.

This changeset imports documention for gdImage to gdImagePng*() into
Natural Docs.  Documention is based on the text of the original
manual, version 2.0.36 but adapted to better suit the format.
Subsequent changesets will introduce docs for subsequent manual
entries.

naturaldocs, when present, is invoked by bootstrap.sh.  The completed
manual will be in docs/naturaldocs/html/index.html.  It can also be
explicitly invoked by running docs/naturaldocs/run_docs.sh.

This change also removed docs/naturaldocs/project/Menu.txt, since it
currently contains no non-generated content and is prone to introduce
noise into the changeset.

1 files changed, 144 insertions, 12 deletions

diff --git a/src/gd.h b/src/gd.h
index 4e643ff..96c302d 100644
--- a/src/gd.h
+++ b/src/gd.h
@@ -368,6 +368,47 @@ typedef struct
 }
 gdPointF, *gdPointFPtr;
 
+
+/*
+  Group: Types
+
+  typedef: gdFont
+
+  typedef: gdFontPtr
+
+  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
+  return one.
+
+  You can provide your own font data by providing such a structure and
+  the associated pixel array. You can determine the width and height
+  of a single character in a font by examining the w and h members of
+  the structure. If you will not be creating your own fonts, you will
+  not need to concern yourself with the rest of the components of this
+  structure.
+
+  Please see the files gdfontl.c and gdfontl.h for an example of
+  the proper declaration of this structure. 
+
+  > typedef struct {
+  >   // # of characters in font
+  >   int nchars;
+  >   // First character is numbered... (usually 32 = space)
+  >   int offset;
+  >   // Character width and height
+  >   int w;
+  >   int h;
+  >   // Font data; array of characters, one row after another.
+  >   // Easily included in code, also easily loaded from
+  >   // data files.
+  >   char *data;
+  > } gdFont;
+
+  gdFontPtr is a pointer to gdFont.
+
+*/
 typedef struct {
 	/* # of characters in font */
 	int nchars;
@@ -459,11 +500,34 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromBmpPtr (int size, void *data);
 BGD_DECLARE(gdImagePtr) gdImageCreateFromBmpCtx (gdIOCtxPtr infile);
 BGD_DECLARE(gdImagePtr) gdImageCreateFromFile(const char *filename);
 
-/* A custom data source. */
-/* The source function must return -1 on error, otherwise the number
-   of bytes fetched. 0 is EOF, not an error! */
-/* context will be passed to your source function. */
 
+/*
+  Group: Types
+
+  typedef: gdSource
+
+  typedef: gdSourcePtr
+
+    *Note:* This interface is *obsolete* and kept only for
+    *compatibility.  Use <gdIOCtx> instead.
+
+    Represents a source from which a PNG can be read. Programmers who
+    do not wish to read PNGs from a file can provide their own
+    alternate input mechanism, using the <gdImageCreateFromPngSource>
+    function. See the documentation of that function for an example of
+    the proper use of this type.
+
+    > typedef struct {
+    >         int (*source) (void *context, char *buffer, int len);
+    >         void *context;
+    > } gdSource, *gdSourcePtr;
+
+    The source function must return -1 on error, otherwise the number
+    of bytes fetched. 0 is EOF, not an error!
+
+   'context' will be passed to your source function.
+
+*/
 typedef struct {
 	int (*source) (void *context, char *buffer, int len);
 	void *context;
@@ -566,9 +630,23 @@ BGD_DECLARE(char *) gdImageStringFT (gdImage * im, int *brect, int fg, char *fon
                                      double ptsize, double angle, int x, int y,
                                      char *string);
 
+
+/*
+  Group: Types
+
+  typedef: gdFTStringExtra
+
+  typedef: gdFTStringExtraPtr
+
+  A structure and associated pointer type used to pass additional
+  parameters to the <gdImageStringFTEx> function. See
+  <gdImageStringFTEx> for the structure definition.
+
+  Thanks to Wez Furlong.
+*/
+
 /* 2.0.5: provides an extensible way to pass additional parameters.
    Thanks to Wez Furlong, sorry for the delay. */
-
 typedef struct {
 	int flags;		/* Logical OR of gdFTEX_ values */
 	double linespacing;	/* fine tune line spacing for '\n' */
@@ -636,7 +714,23 @@ BGD_DECLARE(char *) gdImageStringFTEx (gdImage * im, int *brect, int fg, char *f
                                        double ptsize, double angle, int x, int y,
                                        char *string, gdFTStringExtraPtr strex);
 
-/* Point type for use in polygon drawing. */
+
+/*
+  Group: Types
+
+  typedef: gdPoint
+
+  typedef: gdPointPtr
+
+  Represents a point in the coordinate space of the image; used by
+  <gdImagePolygon>, <gdImageOpenPolygon> and <gdImageFilledPolygon>
+  for polygon drawing.
+
+  > typedef struct {
+  >     int x, y;
+  > } gdPoint, *gdPointPtr;
+
+*/
 typedef struct {
 	int x, y;
 }
@@ -816,9 +910,22 @@ BGD_DECLARE(void *) gdImageWebpPtr (gdImagePtr im, int *size);
 BGD_DECLARE(void *) gdImageWebpPtrEx (gdImagePtr im, int *size, int quantization);
 BGD_DECLARE(void) gdImageWebpCtx (gdImagePtr im, gdIOCtx * outfile, int quantization);
 
-/* Legal values for Disposal. gdDisposalNone is always used by
-   the built-in optimizer if previm is passed. */
 
+/**
+ * Group: GifAnim
+ * 
+ *   Legal values for Disposal. gdDisposalNone is always used by
+ *   the built-in optimizer if previm is passed.
+ *
+ * Constants: gdImageGifAnim
+ *
+ *   gdDisposalUnknown              - Not recommended
+ *   gdDisposalNone                 - Preserve previous frame
+ *   gdDisposalRestoreBackground    - First allocated color of palette
+ *   gdDisposalRestorePrevious      - Restore to before start of frame
+ *
+ * See also: <gdImageGifAnimAdd>
+ */
 enum {
 	gdDisposalUnknown,
 	gdDisposalNone,
@@ -836,11 +943,36 @@ BGD_DECLARE(void *) gdImageGifAnimBeginPtr(gdImagePtr im, int *size, int GlobalC
 BGD_DECLARE(void *) gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm);
 BGD_DECLARE(void *) gdImageGifAnimEndPtr(int *size);
 
-/* A custom data sink. For backwards compatibility. Use gdIOCtx
-   instead. The sink function must return -1 on error, otherwise the
-   number of bytes written, which must be equal to len.  Context will
-   be passed to your sink function.
+
+
+/*
+  Group: Types
+
+  typedef: gdSink
+
+  typedef: gdSinkPtr
+
+    *Note:* This interface is *obsolete* and kept only for
+    *compatibility.  Use <gdIOCtx> instead.
+
+    Represents a "sink" (destination) to which a PNG can be
+    written. Programmers who do not wish to write PNGs to a file can
+    provide their own alternate output mechanism, using the
+    <gdImagePngToSink> function. See the documentation of that
+    function for an example of the proper use of this type.
+
+    > typedef struct {
+    >     int (*sink) (void *context, char *buffer, int len);
+    >     void *context;
+    > } gdSink, *gdSinkPtr;
+
+    The _sink_ function must return -1 on error, otherwise the number of
+    bytes written, which must be equal to len.
+
+    _context_ will be passed to your sink function.
+
 */
+
 typedef struct {
 	int (*sink) (void *context, const char *buffer, int len);
 	void *context;