Start adding doxygen documentation to the library interface.

svn path=/import/jshaw/libsprite/; revision=10018

4 files changed, 151 insertions, 68 deletions

diff --git a/trunk/Makefile b/trunk/Makefile
index 7f86a41..873f212 100644
--- a/trunk/Makefile
+++ b/trunk/Makefile
@@ -1,6 +1,7 @@
 AR = ar
 CC = gcc
 LD = gcc
+DOXYGEN = doxygen
 ARFLAGS = -cru
 CFLAGS = -Wall -Wextra -Wundef -Wpointer-arith -Wcast-align \
 	-Wwrite-strings -Wstrict-prototypes \
@@ -9,7 +10,9 @@ CFLAGS = -Wall -Wextra -Wundef -Wpointer-arith -Wcast-align \
 	-Wmissing-format-attribute -Wunused -Wunreachable-code \
 	-Wformat=2 -Werror-implicit-function-declaration
 LDFLAGS = -L./
-#-Wmissing-declarations -Wmissing-prototypes 
+#-Wmissing-declarations -Wmissing-prototypes
+
+all: example palette2c
 
 example: librosprite.a example.o
 	${LD} -g -o $@ example.o ${LDFLAGS} -lrosprite -lSDL
@@ -23,5 +26,9 @@ librosprite.a: librosprite.o
 %.o: %.c
 	${CC} -c -g ${CFLAGS} -o $@ $<
 
+docs:
+	${DOXYGEN}
+
 clean:
-	rm -f $(wildcard *.o) $(wildcard *.a) example palette
\ No newline at end of file
+	rm -f $(wildcard *.o) $(wildcard *.a) example palette
+	rm -rf doc
\ No newline at end of file
diff --git a/trunk/example.c b/trunk/example.c
index d0dad5e..5de3139 100644
--- a/trunk/example.c
+++ b/trunk/example.c
@@ -119,7 +119,7 @@ int main(int argc, char *argv[])
 	for (uint32_t i = 0; i < sprite_area->sprite_count; i++) {
 		struct rosprite* sprite = sprite_area->sprites[i];
 		printf("\nname %s\n", sprite->name);
-		printf("color_model %s\n", sprite->mode.color_model == rosprite_rgb ? "RGB" : "CMYK");
+		printf("color_model %s\n", sprite->mode.color_model == ROSPRITE_RGB ? "RGB" : "CMYK");
 		printf("colorbpp %u\n", sprite->mode.colorbpp);
 		printf("xdpi %u\n", sprite->mode.xdpi);
 		printf("ydpi %u\n", sprite->mode.ydpi);
diff --git a/trunk/librosprite.c b/trunk/librosprite.c
index 5309488..fcea0d0 100644
--- a/trunk/librosprite.c
+++ b/trunk/librosprite.c
@@ -50,60 +50,60 @@ struct rosprite_mem_context {
 };
 
 static const struct rosprite_mode oldmodes[] = {
-/*0*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*1*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*2*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-
-/*3*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = rosprite_rgb },
-
-/*4*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*5*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-
-/*6*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = rosprite_rgb },
-/*7*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = rosprite_rgb },
-
-/*8*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*9*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*10*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-/*11*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*12*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*13*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*14*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*15*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*16*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*17*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*18*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*19*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*20*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*21*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*22*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi =180, .ydpi = 90, .color_model = rosprite_rgb },
-/*23*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*24*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*25*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*26*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*27*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*28*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*29*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*30*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*31*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*32*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*33*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*34*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*35*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*36*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*37*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*38*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*39*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*40*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*41*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*42*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*43*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*44*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*45*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*46*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*47*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*48*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 90, .color_model = rosprite_rgb },
-/*49*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 90, .color_model = rosprite_rgb }
+/*0*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*1*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*2*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+
+/*3*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = ROSPRITE_RGB },
+
+/*4*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*5*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+
+/*6*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = ROSPRITE_RGB },
+/*7*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0,  .ydpi = 0,  .color_model = ROSPRITE_RGB },
+
+/*8*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*9*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*10*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*11*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*12*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*13*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*14*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*15*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*16*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*17*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*18*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*19*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*20*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*21*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*22*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi =180, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*23*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*24*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*25*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*26*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*27*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*28*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*29*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*30*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*31*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*32*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*33*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*34*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*35*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*36*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*37*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*38*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*39*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*40*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*41*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*42*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*43*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*44*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*45*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*46*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*47*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*48*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*49*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 90, .color_model = ROSPRITE_RGB }
 };
 
 /* table for converting a 5bit channel into an 8bit channel (used for 16bpp to 32bpp conversion) */
@@ -279,7 +279,7 @@ static rosprite_error sprite_get_mode(uint32_t spriteMode, struct rosprite_mode*
 		mode.xdpi = (spriteMode & 0x07ffc000) >> 14; /* preserve bits 14-26 only */
 		mode.ydpi = (spriteMode & 0x00003ffe) >> 1; /* preserve bits 1-13 only */
 
-		mode.color_model = rosprite_rgb;
+		mode.color_model = ROSPRITE_RGB;
 		switch (spriteType) {
 		case 1:
 			mode.colorbpp = 1; break;
@@ -295,7 +295,7 @@ static rosprite_error sprite_get_mode(uint32_t spriteMode, struct rosprite_mode*
 			mode.colorbpp = 32; break;
 		case 7:
 			mode.colorbpp = 32;
-			mode.color_model = rosprite_cmyk;
+			mode.color_model = ROSPRITE_CMYK;
 			break;
 		case 8:
 			mode.colorbpp = 24; break;
@@ -375,7 +375,7 @@ static uint32_t sprite_upscale_color(uint32_t pixel, struct rosprite_mode* mode,
 {
 	switch (mode->colorbpp) {
 	case 32:
-		if (mode->color_model == rosprite_rgb) {
+		if (mode->color_model == ROSPRITE_RGB) {
 			/* swap from 0xAABBGGRR to 0xRRGGBBAA */
 			pixel = BSWAP(pixel);
 
@@ -730,9 +730,6 @@ void rosprite_destroy_sprite_area(struct rosprite_area* sprite_area)
 
 rosprite_error rosprite_load_palette(reader reader, void* ctx, struct rosprite_palette** result)
 {
-	/* Palette file is in groups of 6 bytes, each is a VDU 19 (set palette)
-	 * http://www.drobe.co.uk/show_manual.php?manual=/sh-cgi?manual=Vdu%26page=19 */
-
 	/* TODO: currently assume palette has linear entries (2nd byte in is 00, 01, 02 etc) */
 	struct rosprite_palette* palette = malloc(sizeof(struct rosprite_palette));
 
diff --git a/trunk/librosprite.h b/trunk/librosprite.h
index bbe7f7d..442163c 100644
--- a/trunk/librosprite.h
+++ b/trunk/librosprite.h
@@ -1,3 +1,21 @@
+/**
+ * \mainpage
+ *
+ * librosprite is a library for reading RISC OS sprite files.  The following subformats are supported:
+ * <ul>
+ *   <li>1-bit and 8-bit transparency masks</li>
+ *   <li>Sprites with custom palettes</li>
+ *   <li>Standard RISC OS 1-bit, 2-bit palettes, and 4-bit and 8-bit colour palettes</li>
+ *   <li>Old-style sprites with most screen modes from 0-49 supported</li>
+ *   <li>32bpp CMYK</li>
+ *   <li>Inline alpha channel, as used by Photodesk and Tinct</li>
+ * </ul>
+ */
+
+/**
+ * \file librosprite.h
+ */
+
 #ifndef ROSPRITE_H
 #define ROSPRITE_H
 
@@ -7,12 +25,18 @@
 
 typedef enum { ROSPRITE_OK, ROSPRITE_NOMEM, ROSPRITE_EOF, ROSPRITE_BADMODE } rosprite_error;
 
-typedef enum { rosprite_rgb, rosprite_cmyk } rosprite_color_model;
+typedef enum { ROSPRITE_RGB, ROSPRITE_CMYK } rosprite_color_model;
 
+/**
+ * A reader interface used to load sprite files.
+ */
 typedef int (*reader)(uint8_t* buf, size_t count, void* ctx);
 
 struct rosprite_file_context;
 
+/**
+ * A sprite area comprises zero more rosprites.  Optionally, it may also have an extension_words block.
+ */
 struct rosprite_area {
 	uint32_t extension_size; /* size of extension_words in bytes */
 	uint8_t* extension_words;
@@ -20,7 +44,13 @@ struct rosprite_area {
 	struct rosprite** sprites; /* array of length sprite_count */
 };
 
+/**
+ * A sprite mode defines the colour depth, colour model and bitmap resolution of a sprite.
+ */
 struct rosprite_mode {
+	/**
+	 * The bits per colour channel.  Legal values are 1, 2, 4, 8, 16, 24 and 32.
+	 */
 	uint32_t colorbpp;
 	/* maskbpp denotes the amount of alpha bpp used
 	 * while mask_width is the bits used to store the mask.
@@ -30,7 +60,15 @@ struct rosprite_mode {
 	 */
 	uint32_t maskbpp;
 	uint32_t mask_width; /* in pixels */
+
+	/**
+	 * Horizontal dots per inch.  Typical values are 22, 45, 90 and 180.
+	 */
 	uint32_t xdpi;
+
+	/**
+	 * Vertical dots per inch.  Typical values are 22, 45, 90 and 180.
+	 */
 	uint32_t ydpi;
 	rosprite_color_model color_model;
 };
@@ -40,15 +78,35 @@ struct rosprite_palette {
 	uint32_t* palette;
 };
 
+/**
+ * A sprite is a bitmap image which has a mode, width and height.
+ */
 struct rosprite {
-	unsigned char name[13]; /* last byte for 0 terminator */
+
+	/**
+	 * The sprite name.  This may be up to 12 characters long, and must be zero terminated.
+	 */
+	unsigned char name[13];
 	struct rosprite_mode mode;
 	bool has_mask;
 	bool has_palette;
 	uint32_t palettesize; /* in number of entries (each entry is a word) */
 	uint32_t* palette;
-	uint32_t width; /* width in pixels */
-	uint32_t height; /* height in pixels */
+
+	/**
+	 * Width in pixels
+	 */
+	uint32_t width;
+
+	/**
+	 * Height in pixels
+	 */
+	uint32_t height;
+
+	/**
+	 * Image data is a series of words, appearing on screen left-to-right, top-to-bottom.
+	 * Each word takes the form 0xRRGGBBAA.  A is the alpha channel, where 0 is transparent, and 255 is opaque.
+	 */
 	uint32_t* image; /* image data in 0xRRGGBBAA words */
 };
 
@@ -62,11 +120,32 @@ rosprite_error rosprite_create_mem_context(uint8_t* p, unsigned long total_size,
 void rosprite_destroy_mem_context(struct rosprite_mem_context* ctx);
 int rosprite_mem_reader(uint8_t* buf, size_t count, void* ctx);
 
+/**
+ * Load a rosprite_area using the reader provided.
+ * Clients must call rosprite_destroy_sprite_area() to dispose of the rosprite_area.
+ * \param[out] result The pointer to be populated by this function.
+ */
 rosprite_error rosprite_load(reader reader, void* ctx, struct rosprite_area** result);
+
+/**
+ * Dispose of a rosprite_area and its children.
+ */
 void rosprite_destroy_sprite_area(struct rosprite_area *);
 
+/**
+ * Load a RISC OS palette file.  A palette file has RISC OS filetype 0xFED,
+ * and is a series of VDU 19 Set Palette commands, each command being 6 bytes long.
+ *
+ * Clients must call rosprite_destroy_palette() to dispose of the rosprite_palette.
+ *
+ * \param[out] result The pointer to be populated by this function.
+ * \see http://www.drobe.co.uk/show_manual.php?manual=/sh-cgi?manual=Vdu%26page=19
+ */
 rosprite_error rosprite_load_palette(reader reader, void* ctx, struct rosprite_palette** result);
-void rosprite_destroy_palette(struct rosprite_palette *);
 
+/**
+ * Dispose of a rosprite_palette and its children.
+ */
+void rosprite_destroy_palette(struct rosprite_palette *);
 
 #endif