Add doxygen config and update formatting and doc comments

1 files changed, 141 insertions, 66 deletions

diff --git a/include/libnsgif.h b/include/libnsgif.h
index 462c354..33b4b19 100644
--- a/include/libnsgif.h
+++ b/include/libnsgif.h
@@ -7,8 +7,9 @@
  *                http://www.opensource.org/licenses/mit-license.php
  */
 
-/** \file
- * Progressive animated GIF file decoding (interface).
+/**
+ * \file
+ * Interface to progressive animated GIF file decoding.
  */
 
 #ifndef _LIBNSGIF_H_
@@ -17,42 +18,53 @@
 #include <stdbool.h>
 #include <inttypes.h>
 
-/*	Error return values
-*/
+/* Error return values */
 typedef enum {
-	GIF_WORKING = 1,
-	GIF_OK = 0,
-	GIF_INSUFFICIENT_FRAME_DATA = -1,
-	GIF_FRAME_DATA_ERROR = -2,
-	GIF_INSUFFICIENT_DATA = -3,
-	GIF_DATA_ERROR = -4,
-	GIF_INSUFFICIENT_MEMORY = -5,
-	GIF_FRAME_NO_DISPLAY = -6,
-	GIF_END_OF_FRAME = -7
+        GIF_WORKING = 1,
+        GIF_OK = 0,
+        GIF_INSUFFICIENT_FRAME_DATA = -1,
+        GIF_FRAME_DATA_ERROR = -2,
+        GIF_INSUFFICIENT_DATA = -3,
+        GIF_DATA_ERROR = -4,
+        GIF_INSUFFICIENT_MEMORY = -5,
+        GIF_FRAME_NO_DISPLAY = -6,
+        GIF_END_OF_FRAME = -7
 } gif_result;
 
-/*	The GIF frame data
-*/
+/** GIF frame data */
 typedef struct gif_frame {
-  	bool display;				/**< whether the frame should be displayed/animated */
-  	unsigned int frame_delay;		/**< delay (in cs) before animating the frame */
-	/**	Internal members are listed below
-	*/
-  	unsigned int frame_pointer;		/**< offset (in bytes) to the GIF frame data */
-  	bool virgin;				/**< whether the frame has previously been used */
-	bool opaque;				/**< whether the frame is totally opaque */
-	bool redraw_required;			/**< whether a forcable screen redraw is required */
-	unsigned char disposal_method;		/**< how the previous frame should be disposed; affects plotting */
-	bool transparency;	 		/**< whether we acknoledge transparency */
-	unsigned char transparency_index;	/**< the index designating a transparent pixel */
-	unsigned int redraw_x;			/**< x co-ordinate of redraw rectangle */
-	unsigned int redraw_y;			/**< y co-ordinate of redraw rectangle */
-	unsigned int redraw_width;		/**< width of redraw rectangle */
-	unsigned int redraw_height;		/**< height of redraw rectangle */
+        /** whether the frame should be displayed/animated */
+        bool display;
+        /** delay (in cs) before animating the frame */
+        unsigned int frame_delay;
+
+        /* Internal members are listed below */
+
+        /** offset (in bytes) to the GIF frame data */
+        unsigned int frame_pointer;
+        /** whether the frame has previously been used */
+        bool virgin;
+        /** whether the frame is totally opaque */
+        bool opaque;
+        /** whether a forcable screen redraw is required */
+        bool redraw_required;
+        /** how the previous frame should be disposed; affects plotting */
+        unsigned char disposal_method;
+        /** whether we acknoledge transparency */
+        bool transparency;
+        /** the index designating a transparent pixel */
+        unsigned char transparency_index;
+        /** x co-ordinate of redraw rectangle */
+        unsigned int redraw_x;
+        /** y co-ordinate of redraw rectangle */
+        unsigned int redraw_y;
+        /** width of redraw rectangle */
+        unsigned int redraw_width;
+        /** height of redraw rectangle */
+        unsigned int redraw_height;
 } gif_frame;
 
-/*	API for Bitmap callbacks
-*/
+/* API for Bitmap callbacks */
 typedef void* (*gif_bitmap_cb_create)(int width, int height);
 typedef void (*gif_bitmap_cb_destroy)(void *bitmap);
 typedef unsigned char* (*gif_bitmap_cb_get_buffer)(void *bitmap);
@@ -60,49 +72,112 @@ typedef void (*gif_bitmap_cb_set_opaque)(void *bitmap, bool opaque);
 typedef bool (*gif_bitmap_cb_test_opaque)(void *bitmap);
 typedef void (*gif_bitmap_cb_modified)(void *bitmap);
 
-/*	The Bitmap callbacks function table
-*/
+/** Bitmap callbacks function table */
 typedef struct gif_bitmap_callback_vt {
-	gif_bitmap_cb_create bitmap_create;		/**< Create a bitmap. */
-	gif_bitmap_cb_destroy bitmap_destroy;		/**< Free a bitmap. */
-	gif_bitmap_cb_get_buffer bitmap_get_buffer;	/**< Return a pointer to the pixel data in a bitmap. */
-	/**	Members below are optional
-	*/
-	gif_bitmap_cb_set_opaque bitmap_set_opaque;	/**< Sets whether a bitmap should be plotted opaque. */
-	gif_bitmap_cb_test_opaque bitmap_test_opaque;	/**< Tests whether a bitmap has an opaque alpha channel. */
-	gif_bitmap_cb_modified bitmap_modified;	/**< The bitmap image has changed, so flush any persistant cache. */
+        /** Create a bitmap. */
+        gif_bitmap_cb_create bitmap_create;
+        /** Free a bitmap. */
+        gif_bitmap_cb_destroy bitmap_destroy;
+        /** Return a pointer to the pixel data in a bitmap. */
+        gif_bitmap_cb_get_buffer bitmap_get_buffer;
+
+        /* Members below are optional */
+
+        /** Sets whether a bitmap should be plotted opaque. */
+        gif_bitmap_cb_set_opaque bitmap_set_opaque;
+        /** Tests whether a bitmap has an opaque alpha channel. */
+        gif_bitmap_cb_test_opaque bitmap_test_opaque;
+        /** The bitmap image has changed, so flush any persistant cache. */
+        gif_bitmap_cb_modified bitmap_modified;
 } gif_bitmap_callback_vt;
 
-/*	The GIF animation data
-*/
+/** GIF animation data */
 typedef struct gif_animation {
-	gif_bitmap_callback_vt bitmap_callbacks;	/**< callbacks for bitmap functions */
-	unsigned char *gif_data;			/**< pointer to GIF data */
-	unsigned int width;				/**< width of GIF (may increase during decoding) */
-	unsigned int height;				/**< heigth of GIF (may increase during decoding) */
-	unsigned int frame_count;			/**< number of frames decoded */
-	unsigned int frame_count_partial;		/**< number of frames partially decoded */
-	gif_frame *frames;				/**< decoded frames */
-	int decoded_frame;				/**< current frame decoded to bitmap */
-	void *frame_image;				/**< currently decoded image; stored as bitmap from bitmap_create callback */
-	int loop_count;					/**< number of times to loop animation */
-	gif_result current_error;			/**< current error type, or 0 for none*/
-	/**	Internal members are listed below
-	*/
-	unsigned int buffer_position;			/**< current index into GIF data */
-	unsigned int buffer_size;			/**< total number of bytes of GIF data available */
-	unsigned int frame_holders;			/**< current number of frame holders */
-	unsigned int background_index;			/**< index in the colour table for the background colour */
-	unsigned int aspect_ratio;			/**< image aspect ratio (ignored) */
-	unsigned int colour_table_size;		/**< size of colour table (in entries) */
-	bool global_colours;				/**< whether the GIF has a global colour table */
-	unsigned int *global_colour_table;		/**< global colour table */
-	unsigned int *local_colour_table;		/**< local colour table */
+        /** callbacks for bitmap functions */
+        gif_bitmap_callback_vt bitmap_callbacks;
+        /** pointer to GIF data */
+        unsigned char *gif_data;
+        /** width of GIF (may increase during decoding) */
+        unsigned int width;
+        /** heigth of GIF (may increase during decoding) */
+        unsigned int height;
+        /** number of frames decoded */
+        unsigned int frame_count;
+        /** number of frames partially decoded */
+        unsigned int frame_count_partial;
+        /** decoded frames */
+        gif_frame *frames;
+        /** current frame decoded to bitmap */
+        int decoded_frame;
+        /** currently decoded image; stored as bitmap from bitmap_create callback */
+        void *frame_image;
+        /** number of times to loop animation */
+        int loop_count;
+        /** current error type, or 0 for none */
+        gif_result current_error;
+
+        /* Internal members are listed below */
+
+        /** current index into GIF data */
+        unsigned int buffer_position;
+        /** total number of bytes of GIF data available */
+        unsigned int buffer_size;
+        /** current number of frame holders */
+        unsigned int frame_holders;
+        /** index in the colour table for the background colour */
+        unsigned int background_index;
+        /** image aspect ratio (ignored) */
+        unsigned int aspect_ratio;
+        /** size of colour table (in entries) */
+        unsigned int colour_table_size;
+        /** whether the GIF has a global colour table */
+        bool global_colours;
+        /** global colour table */
+        unsigned int *global_colour_table;
+        /** local colour table */
+        unsigned int *local_colour_table;
 } gif_animation;
 
+/**
+ * Initialises necessary gif_animation members.
+ */
 void gif_create(gif_animation *gif, gif_bitmap_callback_vt *bitmap_callbacks);
+
+/**
+ * Initialises any workspace held by the animation and attempts to decode
+ * any information that hasn't already been decoded.
+ * If an error occurs, all previously decoded frames are retained.
+ *
+ * @return Error return value.
+ *         - GIF_FRAME_DATA_ERROR for GIF frame data error
+ *         - GIF_INSUFFICIENT_FRAME_DATA for insufficient data to process
+ *                                     any more frames
+ *         - GIF_INSUFFICIENT_MEMORY for memory error
+ *         - GIF_DATA_ERROR for GIF error
+ *         - GIF_INSUFFICIENT_DATA for insufficient data to do anything
+ *         - GIF_OK for successful decoding
+ *         - GIF_WORKING for successful decoding if more frames are expected
+ */
 gif_result gif_initialise(gif_animation *gif, size_t size, unsigned char *data);
+
+/**
+ * Decodes a GIF frame.
+ *
+ * @return Error return value. If a frame does not contain any image data,
+ *		GIF_OK is returned and gif->current_error is set to
+ *		GIF_FRAME_NO_DISPLAY
+ *         - GIF_FRAME_DATA_ERROR for GIF frame data error
+ *         - GIF_INSUFFICIENT_FRAME_DATA for insufficient data to complete the frame
+ *         - GIF_DATA_ERROR for GIF error (invalid frame header)
+ *         - GIF_INSUFFICIENT_DATA for insufficient data to do anything
+ *         - GIF_INSUFFICIENT_MEMORY for insufficient memory to process
+ *         - GIF_OK for successful decoding
+ */
 gif_result gif_decode_frame(gif_animation *gif, unsigned int frame);
+
+/**
+ * Releases any workspace held by a gif
+ */
 void gif_finalise(gif_animation *gif);
 
 #endif