Added more docs, mostly header stuff, but some real docs in

IMB_imbuf_types.h and amiga.c

16 files changed, 398 insertions, 40 deletions

diff --git a/source/blender/imbuf/IMB_imbuf_types.h b/source/blender/imbuf/IMB_imbuf_types.h
index 02037a00bbe..4ebcee2962d 100644
--- a/source/blender/imbuf/IMB_imbuf_types.h
+++ b/source/blender/imbuf/IMB_imbuf_types.h
@@ -50,34 +50,44 @@
 struct _AviMovie;
 struct Mdec;
 
-/* the basic imbuf type */
-
+/**
+ * \brief The basic imbuf type
+ * \ingroup imbuf
+ * This is the abstraction of an image.  ImBuf is the basic type used for all
+ * imbuf operations.
+ *
+ */
 typedef struct ImBuf{
-	short	x,y;		/* width in pixels, height in scanlines */
-	short	skipx;		/* width in ints to get to the next scanline */
-	unsigned char	depth;		/* active amount of bits/bitplanes */
-	unsigned char	cbits;		/* amount of active bits in cmap */
-	unsigned short	mincol;
-	unsigned short	maxcol;
-	int	type;		/* 0=abgr, 1=bitplanes */
-	int	ftype;
-	unsigned int	*cmap;		/* int array van kleuren */
-	unsigned int	*rect;		/* databuffer */
-	unsigned int	**planes;	/* bitplanes */
-	int	flags;
-	int	mall;		/* what is malloced internal, and can be freed */
-	short	xorig, yorig;
-	char	name[1023];
-	char	namenull;
-	int	userflags;
-	int	*zbuf;
-	void *userdata;
-	unsigned char *encodedbuffer;
-	unsigned int   encodedsize;
-	unsigned int   encodedbuffersize;
+	short	x;		/**< Width in pixels */
+	short	y;		/**< Height in scanlines */
+	short	skipx;		/**< Width in ints to get to the next scanline */
+	unsigned char	depth;		/**< Active amount of bits/bitplanes */
+	unsigned char	cbits;		/**< Amount of active bits in cmap */
+	unsigned short	mincol;		/**< First active color?*/
+	unsigned short	maxcol;		/**< Last active color?*/
+	int	type;		/**< 0=abgr, 1=bitplanes */
+	int	ftype;		/**< File type */
+	unsigned int	*cmap;		/**< Color map data. */
+	unsigned int	*rect;		/**< databuffer */
+	unsigned int	**planes;	/**< bitplanes */
+	int	flags;		/**< Controls which components should exist. */
+	int	mall;		/**< what is malloced internal, and can be freed */
+	short	xorig:		/**< X origin.  What is this relative to? */
+	short	yorig;		/**< Y origin.  What is this relative to? */
+	char	name[1023];		/**< The file name */
+	char	namenull;		/**< What does this do?*/
+	int	userflags;		/**< What does this do? Holds an enum ImBuf_userflagsMask?*/
+	int	*zbuf;		/**< A z buffer */
+	void *userdata;		/**< What does this do?*/
+	unsigned char *encodedbuffer; 		/** What is an encoded buffer? */
+	unsigned int   encodedsize;		/** What is an encoded buffer? */
+	unsigned int   encodedbuffersize;		/** What is an encoded buffer? */
 } ImBuf;
 
 /* Moved from BKE_bmfont_types.h because it is a userflag bit mask. */
+/**
+ * \brief Flags for the user?
+ */
 typedef enum {
 	IB_BITMAPFONT = 1 << 0,
 	IB_BITMAPDIRTY = 1 << 1
@@ -90,76 +100,241 @@ typedef enum {
  * probably imbuf_intern only. This will need to be merged later
  * on. */
 
+/**
+ * \brief Rectangle flag
+ */
 #define IB_rect			(1 << 0)
+/**
+ * \brief Bitmap Planes flag
+ */
 #define IB_planes		(1 << 1)
+/**
+ * \brief Color map flag
+ */
 #define IB_cmap			(1 << 2)
 
+/**
+ * \brief Vertex flag
+ */
 #define IB_vert			(1 << 4)
+/**
+ * \brief Free Memory flag
+ */
 #define IB_freem		(1 << 6)
+/**
+ * \brief Test flag
+ */
 #define IB_test			(1 << 7)
 
+/**
+ * \brief True Type object??
+ */
 #define IB_ttob			(1 << 8)
 #define IB_subdlta		(1 << 9)
+/**
+ * \brief Video fields flag
+ */
 #define IB_fields		(1 << 11)
+/**
+ * \brief Zbuffer flag
+ */
 #define IB_zbuf			(1 << 13)
 
+/**
+ * \brief Memory flag?
+ */
 #define IB_mem			(1 << 14)
 
+/**
+ * \brief .ami (amiga) filetype
+ */
 #define AMI	    (1 << 31)
+/**
+ * \brief .png filetype
+ */
 #define PNG	    (1 << 30)
+/**
+ * \brief .??? (Anim) filetype
+ */
 #define Anim	(1 << 29)
+/**
+ * \brief .tga (targa) filetype
+ */
 #define TGA	    (1 << 28)
+/**
+ * \brief .jpg (JPEG) filetype
+ */
 #define JPG		(1 << 27)
+/**
+ * \brief .bmp filetype
+ */
 #define BMP		(1 << 26)
 #ifdef WITH_QUICKTIME
+/**
+ * \brief .mov? (Quicktime) filetype
+ */
 #define QUICKTIME	(1 << 25)
 #endif
 #ifdef WITH_FREEIMAGE
+/**
+ * \brief .??? (Freeimage) filetype
+ */
 #define FREEIMAGE	(1 << 24)
 #endif
 #ifdef WITH_IMAGEMAGICK
+/**
+ * \brief .im? (ImageMagick) filetype
+ */
 #define IMAGEMAGICK	(1 << 23)
 #endif
 
+/**
+ * \brief tga of type "raw"
+ */
 #define RAWTGA	(TGA | 1)
 
+/**
+ * \brief jpg of type "standard"?
+ */
 #define JPG_STD	(JPG | (0 << 8))
+/**
+ * \brief jpg of type "video"?
+ */
 #define JPG_VID	(JPG | (1 << 8))
+/**
+ * \brief jpg of type "jst"?
+ */
 #define JPG_JST	(JPG | (2 << 8))
+/**
+ * \brief jpg of type "max"?
+ */
 #define JPG_MAX	(JPG | (3 << 8))
+/**
+ * \brief Masks off the last two bytes.
+ */
 #define JPG_MSK	(0xffffff00)
 
+/**
+ * \brief .ham? Anim filetype
+ */
 #define AM_ham	    (0x0800 | AMI)
+/**
+ * \brief .??? Anim filetype
+ */
 #define AM_hbrite   (0x0080 | AMI)
 
+/**
+ * \brief c233 type for Anim filetype
+ */
 #define C233	1
+/**
+ * \brief c233 type for Anim filetype
+ */
 #define YUVX	2
+/**
+ * \brief c233 type for Anim filetype
+ */
 #define HAMX	3
+/**
+ * \brief c233 type for Anim filetype
+ */
 #define TANX	4
 
+/**
+ * \brief Anim file of type c233
+ */
 #define AN_c233			(Anim | C233)
+/**
+ * \brief Anim file of type YUVX
+ */
 #define AN_yuvx			(Anim | YUVX)
+/**
+ * \brief Anim file of type HAMX
+ */
 #define AN_hamx			(Anim | HAMX)
+/**
+ * \brief Anim file of type TANX
+ */
 #define AN_tanx			(Anim | TANX)
 
+/**
+ * \brief Tests if an ImBuf is an Amiga file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_amiga(x)		(x->ftype & AMI)
+/**
+ * \brief Tests if an ImBuf is a ham file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_ham(x)		((x->ftype & AM_ham) == AM_ham)
+/**
+ * \brief Tests if an ImBuf is an hbrite file. 
+ * \param x Must be an ImBuf*
+ */
 #define IS_hbrite(x)	((x->ftype & AM_hbrite) == AM_hbrite)
 
+/**
+ * \brief Tests if an ImBuf is an Anim file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_anim(x)		(x->ftype & Anim)
+/**
+ * \brief Tests if an ImBuf is an Anim hamx.
+ * \param x Must be an ImBuf*
+ */
 #define IS_hamx(x)		(x->ftype == AN_hamx)
+/**
+ * \brief Tests if an ImBuf is a tga file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_tga(x)		(x->ftype & TGA)
+/**
+ * \brief Tests if an ImBuf is a png file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_png(x)		(x->ftype & PNG)
+/**
+ * \brief Tests if an ImBuf is a bmp file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_bmp(x)		(x->ftype & BMP)
 
+/**
+ * \brief Iris filetype.
+ */
 #define IMAGIC 	0732
+/**
+ * \brief Tests if an ImBuf is an Iris file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_iris(x)		(x->ftype == IMAGIC)
 
+/**
+ * \brief Tests if an ImBuf is a JPEG file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_jpg(x)		(x->ftype & JPG)
+/**
+ * \brief Tests if an ImBuf is a standard JPEG file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_stdjpg(x)	((x->ftype & JPG_MSK) == JPG_STD)
+/**
+ * \brief Tests if an ImBuf is a video JPEG file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_vidjpg(x)	((x->ftype & JPG_MSK) == JPG_VID)
+/**
+ * \brief Tests if an ImBuf is a jst JPEG file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_jstjpg(x)	((x->ftype & JPG_MSK) == JPG_JST)
+/**
+ * \brief Tests if an ImBuf is a max JPEG file.
+ * \param x Must be an ImBuf*
+ */
 #define IS_maxjpg(x)	((x->ftype & JPG_MSK) == JPG_MAX)
 
 #endif
 
+
diff --git a/source/blender/imbuf/intern/IMB_allocimbuf.h b/source/blender/imbuf/intern/IMB_allocimbuf.h
index 21dc59a127c..c01c9d60dd7 100644
--- a/source/blender/imbuf/intern/IMB_allocimbuf.h
+++ b/source/blender/imbuf/intern/IMB_allocimbuf.h
@@ -1,4 +1,4 @@
-/**
+/*
  * allocimbuf.h
  *
  * $Id$
@@ -32,6 +32,11 @@
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
 
+/**
+ * \file IMB_allocimbuf.h
+ * \ingroup imbuf
+ * \brief Header file for allocimbuf.c
+ */
 #ifndef IMB_ALLOCIMBUF_H
 #define IMB_ALLOCIMBUF_H
 
diff --git a/source/blender/imbuf/intern/IMB_amiga.h b/source/blender/imbuf/intern/IMB_amiga.h
index eca6b8fbac8..39ca4035753 100644
--- a/source/blender/imbuf/intern/IMB_amiga.h
+++ b/source/blender/imbuf/intern/IMB_amiga.h
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_amiga.h
+ * \ingroup imbuf
+ * \brief Function declarations for amiga.c
+ */
 
 #ifndef IMB_AMIGA_H
 #define IMB_AMIGA_H
diff --git a/source/blender/imbuf/intern/IMB_bitplanes.h b/source/blender/imbuf/intern/IMB_bitplanes.h
index 77832e19177..643c6d57a06 100644
--- a/source/blender/imbuf/intern/IMB_bitplanes.h
+++ b/source/blender/imbuf/intern/IMB_bitplanes.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_bitplanes.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_bitplanes.h
+ * \ingroup imbuf
+ * \brief Function declarations for bitplanes.c
+ */
 
 #ifndef IMB_BITPLANES_H
 #define IMB_BITPLANES_H
diff --git a/source/blender/imbuf/intern/IMB_bmp.h b/source/blender/imbuf/intern/IMB_bmp.h
index 112cfe932ce..fe279849bd0 100644
--- a/source/blender/imbuf/intern/IMB_bmp.h
+++ b/source/blender/imbuf/intern/IMB_bmp.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_bmp.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_bmp.h
+ * \ingroup imbuf
+ * \brief Function declarations for bmp.c
+ */
 
 #ifndef IMB_BMP_H
 #define IMB_BMP_H
diff --git a/source/blender/imbuf/intern/IMB_cmap.h b/source/blender/imbuf/intern/IMB_cmap.h
index 23f5b9f4015..cf6c15ede91 100644
--- a/source/blender/imbuf/intern/IMB_cmap.h
+++ b/source/blender/imbuf/intern/IMB_cmap.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_cmap.h
  *
  * $Id$
@@ -31,7 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
-
+/**
+ * \file IMB_cmap.h
+ * \ingroup imbuf
+ * \brief Function declarations for cmap.c
+ */
 #ifndef IMB_CMAP_H
 #define IMB_CMAP_H
 
diff --git a/source/blender/imbuf/intern/IMB_divers.h b/source/blender/imbuf/intern/IMB_divers.h
index 196ecf3219b..23d71d2c74d 100644
--- a/source/blender/imbuf/intern/IMB_divers.h
+++ b/source/blender/imbuf/intern/IMB_divers.h
@@ -1,4 +1,4 @@
-/**
+/*
  * divers.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_divers.h
+ * \ingroup imbuf
+ * \brief Function declarations for divers.c
+ */
 
 #ifndef IMB_DIVERS_H
 #define IMB_DIVERS_H
diff --git a/source/blender/imbuf/intern/IMB_filter.h b/source/blender/imbuf/intern/IMB_filter.h
index 7091ee56aa2..c544ae9a04c 100644
--- a/source/blender/imbuf/intern/IMB_filter.h
+++ b/source/blender/imbuf/intern/IMB_filter.h
@@ -1,4 +1,4 @@
-/**
+/*
  * filter.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_filter.h
+ * \ingroup imbuf
+ * \brief Function declarations for filter.c
+ */
 
 #ifndef IMB_FILTER_H
 #define IMB_FILTER_H
diff --git a/source/blender/imbuf/intern/IMB_ham.h b/source/blender/imbuf/intern/IMB_ham.h
index b1b1e7b0c97..e3302542198 100644
--- a/source/blender/imbuf/intern/IMB_ham.h
+++ b/source/blender/imbuf/intern/IMB_ham.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_ham.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_ham.h
+ * \ingroup imbuf
+ * \brief Function declarations for ham.c
+ */
 
 #ifndef IMB_HAM_H
 #define IMB_HAM_H
diff --git a/source/blender/imbuf/intern/IMB_hamx.h b/source/blender/imbuf/intern/IMB_hamx.h
index 8b7f489964e..98cb1366b8b 100644
--- a/source/blender/imbuf/intern/IMB_hamx.h
+++ b/source/blender/imbuf/intern/IMB_hamx.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_hamx.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_hamx.h
+ * \ingroup imbuf
+ * \brief Function declarations for hamx.c
+ */
 
 #ifndef IMB_HAMX_H
 #define IMB_HAMX_H
diff --git a/source/blender/imbuf/intern/IMB_iff.h b/source/blender/imbuf/intern/IMB_iff.h
index 1dbb193d098..c65330bad95 100644
--- a/source/blender/imbuf/intern/IMB_iff.h
+++ b/source/blender/imbuf/intern/IMB_iff.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_iff.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_iff.h
+ * \ingroup imbuf
+ * \brief Function declarations for iff.c
+ */
 
 #ifndef IMB_IFF_H
 #define IMB_IFF_H
diff --git a/source/blender/imbuf/intern/IMB_iris.h b/source/blender/imbuf/intern/IMB_iris.h
index 41457e1fadf..046cff62947 100644
--- a/source/blender/imbuf/intern/IMB_iris.h
+++ b/source/blender/imbuf/intern/IMB_iris.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_iris.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_iris.h
+ * \ingroup imbuf
+ * \brief Function declarations for iris.c
+ */
 
 #ifndef IMB_IRIS_H
 #define IMB_IRIS_H
diff --git a/source/blender/imbuf/intern/IMB_jpeg.h b/source/blender/imbuf/intern/IMB_jpeg.h
index a673d965a4d..db23ebccb87 100644
--- a/source/blender/imbuf/intern/IMB_jpeg.h
+++ b/source/blender/imbuf/intern/IMB_jpeg.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_jpeg.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_jpeg.h
+ * \ingroup imbuf
+ * \brief Function declarations for jpeg.c
+ */
 
 #ifndef IMB_JPEG_H
 #define IMB_JPEG_H
diff --git a/source/blender/imbuf/intern/IMB_png.h b/source/blender/imbuf/intern/IMB_png.h
index f876b8204d8..4623189c636 100644
--- a/source/blender/imbuf/intern/IMB_png.h
+++ b/source/blender/imbuf/intern/IMB_png.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_png.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_png.h
+ * \ingroup imbuf
+ * \brief Function declarations for png_decode.c
+ */
 
 #ifndef IMB_PNG_H
 #define IMB_PNG_H
diff --git a/source/blender/imbuf/intern/IMB_targa.h b/source/blender/imbuf/intern/IMB_targa.h
index f1fdf5f4daa..6aa8f65dca5 100644
--- a/source/blender/imbuf/intern/IMB_targa.h
+++ b/source/blender/imbuf/intern/IMB_targa.h
@@ -1,4 +1,4 @@
-/**
+/*
  * IMB_targa.h
  *
  * $Id$
@@ -31,6 +31,11 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file IMB_targa.h
+ * \ingroup imbuf
+ * \brief Function declarations for targa.c
+ */
 
 #ifndef IMB_TARGA_H
 #define IMB_TARGA_H
diff --git a/source/blender/imbuf/intern/amiga.c b/source/blender/imbuf/intern/amiga.c
index fd753ec683d..2abc2b8c375 100644
--- a/source/blender/imbuf/intern/amiga.c
+++ b/source/blender/imbuf/intern/amiga.c
@@ -31,6 +31,14 @@
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file amiga.c
+ * \brief This file handles loading and saving of amiga files.
+ * \ingroup imbuf
+ * \warning This file contains endian code.  Some way should be found to move
+ * this code out of here.
+ * \help Endian #defines are in multiple files!
+ */
 
 #include "imbuf.h"
 #include "imbuf_patch.h"
@@ -48,9 +56,23 @@
 #endif
 
 /* actually hard coded endianness */
+/**
+ * \brief Makes a 4 bit id for a 32 bit value: Big-endian
+ * \todo How is this used?
+ */
 #define GET_BIG_LONG(x) (((uchar *) (x))[0] << 24 | ((uchar *) (x))[1] << 16 | ((uchar *) (x))[2] << 8 | ((uchar *) (x))[3])
+/**
+ * \brief Makes a 4 bit id for a 16? bit value: Little-endian
+ * \todo How is this used?
+ */
 #define GET_LITTLE_LONG(x) (((uchar *) (x))[3] << 24 | ((uchar *) (x))[2] << 16 | ((uchar *) (x))[1] << 8 | ((uchar *) (x))[0])
+/**
+ * \brief Converts between little and big endian: 32 bit values
+ */
 #define SWAP_L(x) (((x << 24) & 0xff000000) | ((x << 8) & 0xff0000) | ((x >> 8) & 0xff00) | ((x >> 24) & 0xff))
+/**
+ * \brief Converts between little and big endian:  16 bit values
+ */
 #define SWAP_S(x) (((x << 8) & 0xff00) | ((x >> 8) & 0xff))
 
 /* more endianness... should move to a separate file... */
@@ -390,6 +412,16 @@ static uchar *readbody(struct ImBuf *ibuf, uchar *body)
 	return body;
 }
 
+/**
+ * \brief Loads an amiga (.ami) image.
+ * \ingroup imbuf
+ * \param iffmem A pointer to a memory location.
+ * \param flags A set of bit flags determining what parts of the image to load.
+ * \return Returns 0 if loading the image fails, otherwise returns a pointer to an ImBuf.
+ * 
+ * I am fairly certain of what is going on in this function, so if I am
+ * wrong, please let me know, so I can update the docs!
+ */
 struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 {
 	int chunk,totlen,len,*cmap=0,cmaplen,*mem,ftype=0;
@@ -397,16 +429,45 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 	struct BitMapHeader bmhd;
 	struct ImBuf *ibuf=0;
 
+	/**
+	 * \internal The memory address to the data is copiend into mem.
+	 */
 	mem = iffmem;
+	/**
+	 * \internal The w member of the BitMapHeader is initialized to 0 because 
+	 * it will be tested to see if it has been set later.
+	 */
 	bmhd.w = 0;
 
+	/**
+	 * \internal The first three chunks must have the form: FORMxxxxILBM
+	 * else the function returns with 0;
+	 * FORM and ILBM are defined in imbuf_patch.h
+	 */
 	if (GET_ID(mem) != FORM) return (0);
 	if (GET_ID(mem+2) != ILBM) return (0);
+	/**
+	 * \internal The second chunk is the total size of the image.
+	 */
 	totlen= (GET_BIG_LONG(mem+1) + 1) & ~1;
+	/**
+	 * \internal mem is incremented to skip the first three chunks.
+	 */
 	mem += 3;
+	/**
+	 * \internal Anyone know why the total length is decreased by four here?
+	 */
 	totlen -= 4;
 
 
+	/**
+	 * \internal The while loop retrieves at most four blocks of memory:
+	 *  - bmhd: the bit map header
+	 *  - body: which is the image data
+	 *  - cmap: the color map
+	 *  - ftype: the file type (what does CAMG stand for?)
+	 * The body and the bitmap header are required.
+	 */
 	while(totlen > 0){
 		chunk = GET_ID(mem);
 		len= (GET_BIG_LONG(mem+1) + 1) & ~1;
@@ -439,18 +500,36 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 			break;
 		}
 		mem = (int *)((uchar *)mem +len);
+		/**
+		 * \intern Anything after the first BODY ID is discarded.
+		 */
 		if (body) break;
 	}
+	/**
+	 * \internal After the while loop, the existance of body and bmhd are detected.
+	 */
 	if (bmhd.w == 0) return (0);
 	if (body == 0) return (0);
 	
+	/**
+	 * \internal if the IB_test bit is set in flags, don't do masking.
+	 * (I'm not too sure about this)  In any case, allocate the memory
+	 * for the imbuf, and return 0 if this fails.
+	 */
 	if (flags & IB_test) ibuf = IMB_allocImBuf(bmhd.w, bmhd.h, bmhd.nPlanes, 0, 0);
 	else ibuf = IMB_allocImBuf(bmhd.w, bmhd.h, bmhd.nPlanes + (bmhd.masking & 1),0,1);
 
 	if (ibuf == 0) return (0);
 
+	/**
+	 * \internal Set the AMI bit in ftype.
+	 */
 	ibuf->ftype = (ftype | AMI);
 	
+	/**
+	 * \internal If there was a cmap chunk in the data, add the cmap
+	 * to the ImBuf and copy the data there.
+	 */
 	if (cmap){
 		ibuf->mincol = 0;
 		ibuf->maxcol = cmaplen;
@@ -461,11 +540,21 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 		imb_makecolarray(ibuf, cmap, 0);
 	}
 
+	/**
+	 * \internal If the IB_test bit of flags was set, we're done:
+	 * If the IB_freem bit is set, free the data pointed to by iffmem.
+	 * Return the data.
+	 */
 	if (flags & IB_test){
 		if (flags & IB_freem) free(iffmem);
 		return(ibuf);
 	}
 	
+	/**
+	 * \internal Check the bitmap header to see if there is any
+	 * compression.  0 is no, 1 is horizontal, 2 is vertical.
+	 * Load the data according to the type of compression.
+	 */
 	switch (bmhd.compression){
 	case 0:
 		body= readbody(ibuf, body);
@@ -479,23 +568,42 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 		break;
 	}
 
+	/**
+	 * \internal If the IB_freem bit is set, free the data pointed to by iffmem.
+	 */
 	if (flags & IB_freem) free(iffmem);
 
+	/**
+	 * \internal If there was some problem loading the body
+	 * data, free the memory already allocated in ibuf and
+	 * return 0.
+	 */
 	if (body == 0){
 		free (ibuf);
 		return(0);
 	}
 	
+	/**
+	 * \internal Set the bit depth to the number of planes in bmhd.
+	 * This discards the "stencil" data (What is the stencil? Alpha channel?)
+	 */
 	/* forget stencil */
 	ibuf->depth = bmhd.nPlanes;
 	
+	/**
+	 * \internal If the IB_rect bit is set in flags, add the rect and
+	 * get rid of the planes.
+	 */
 	if (flags & IB_rect){
 		imb_addrectImBuf(ibuf);
 		imb_bptolong(ibuf);
 		imb_freeplanesImBuf(ibuf);
+		/**
+		 * \internal If the image has a color map, apply it.
+		 */
 		if (ibuf->cmap){
 			if ((flags & IB_cmap) == 0) IMB_applycmap(ibuf);
-		} else if (ibuf->depth == 18){
+		} else if (ibuf->depth == 18){ /** \internal No color map, and the bit depths is 18, convert to 24-bit */
 			int i,col;
 			unsigned int *rect;
 
@@ -507,7 +615,7 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 				*rect++ = col;
 			}
 			ibuf->depth = 24;
-		} else if (ibuf->depth <= 8) { /* no colormap and no 24 bits: b&w */
+		} else if (ibuf->depth <= 8) { /** \internal No colormap and no 24 bits, so it's b&w */
 			uchar *rect;
 			int size, shift;
 
@@ -529,8 +637,14 @@ struct ImBuf *imb_loadamiga(int *iffmem,int flags)
 		}
 	}
 
+	/**
+	 * \internal Anyone know what IB_ttob is?  What does IMB_flipy do?
+	 */
 	if ((flags & IB_ttob) == 0) IMB_flipy(ibuf);
 
+	/**
+	 * \internal Last thing to do before returning is to flip the bits from rgba to abgr.
+	 */
 	if (ibuf) {
 		if (ibuf->rect) 
 			IMB_convert_rgba_to_abgr(ibuf->x*ibuf->y, ibuf->rect);