* doc/liboil-sections.txt: Documentation? Is he MAD?

* doc/tmpl/liboil-unused.sgml:
* doc/tmpl/liboilfuncs-math.sgml:
* liboil/jpeg/yuv2rgb_c.c:
* liboil/liboilfunction.c:
* liboil/ref/abs.c:
* liboil/ref/argb_paint.c:
* liboil/ref/ayuv2argb.c:
* liboil/ref/composite.c:
* liboil/ref/resample.c:
* liboil/ref/rgb.c:
* liboil/ref/yuv.c:

13 files changed, 474 insertions, 106 deletions

diff --git a/ChangeLog b/ChangeLog
index 49aa41b..e47ca54 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2005-11-11  David Schleef  <ds@schleef.org>
+
+	* doc/liboil-sections.txt: Documentation?  Is he MAD?
+	* doc/tmpl/liboil-unused.sgml:
+	* doc/tmpl/liboilfuncs-math.sgml:
+	* liboil/jpeg/yuv2rgb_c.c:
+	* liboil/liboilfunction.c:
+	* liboil/ref/abs.c:
+	* liboil/ref/argb_paint.c:
+	* liboil/ref/ayuv2argb.c:
+	* liboil/ref/composite.c:
+	* liboil/ref/resample.c:
+	* liboil/ref/rgb.c:
+	* liboil/ref/yuv.c:
+
 2005-11-06  David Schleef  <ds@schleef.org>
 
 	* liboil/Makefile.am: Fix more stuff and reenable MMX
diff --git a/doc/liboil-sections.txt b/doc/liboil-sections.txt
index ca274d0..8c267d8 100644
--- a/doc/liboil-sections.txt
+++ b/doc/liboil-sections.txt
@@ -366,6 +366,12 @@ oil_vectoradd_s8
 oil_vectoradd_u16
 oil_vectoradd_u32
 oil_vectoradd_u8
+oil_vectoradd_s_s8
+oil_vectoradd_s_u8
+oil_vectoradd_s_s16
+oil_vectoradd_s_u16
+oil_vectoradd_s_f32
+oil_vectoradd_s_f64
 oil_squaresum_f64
 oil_sum_f64
 oil_add_f32
diff --git a/doc/tmpl/liboil-unused.sgml b/doc/tmpl/liboil-unused.sgml
index 0ef1f84..929ce90 100644
--- a/doc/tmpl/liboil-unused.sgml
+++ b/doc/tmpl/liboil-unused.sgml
@@ -3390,81 +3390,3 @@ utf8
 
 @test: 
 
-<!-- ##### FUNCTION oil_vectoradd_s_f32 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
-<!-- ##### FUNCTION oil_vectoradd_s_f64 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
-<!-- ##### FUNCTION oil_vectoradd_s_s16 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
-<!-- ##### FUNCTION oil_vectoradd_s_s8 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
-<!-- ##### FUNCTION oil_vectoradd_s_u16 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
-<!-- ##### FUNCTION oil_vectoradd_s_u8 ##### -->
-<para>
-
-</para>
-
-@dest: 
-@dstr: 
-@src1: 
-@sstr1: 
-@src2: 
-@sstr2: 
-@n: 
-
diff --git a/doc/tmpl/liboilfuncs-math.sgml b/doc/tmpl/liboilfuncs-math.sgml
index 2b12845..38890f1 100644
--- a/doc/tmpl/liboilfuncs-math.sgml
+++ b/doc/tmpl/liboilfuncs-math.sgml
@@ -1,11 +1,12 @@
 <!-- ##### SECTION Title ##### -->
-Simple Math
+liboilfuncs-math
 
 <!-- ##### SECTION Short_Description ##### -->
-Function Classes for Simple Arithmetic Operations
+
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -18,7 +19,7 @@ Function Classes for Simple Arithmetic Operations
 
 <!-- ##### FUNCTION oil_abs_f32_f32 ##### -->
 <para>
-Calculates the absolute value of each element.
+
 </para>
 
 @dest: 
@@ -30,7 +31,7 @@ Calculates the absolute value of each element.
 
 <!-- ##### FUNCTION oil_abs_f64_f64 ##### -->
 <para>
-Calculates the absolute value of each element.
+
 </para>
 
 @dest: 
@@ -43,7 +44,6 @@ Calculates the absolute value of each element.
 <!-- ##### FUNCTION oil_abs_u16_s16 ##### -->
 <para>
 
-Calculates the absolute value of each element.
 </para>
 
 @dest: 
@@ -56,7 +56,6 @@ Calculates the absolute value of each element.
 <!-- ##### FUNCTION oil_abs_u32_s32 ##### -->
 <para>
 
-Calculates the absolute value of each element.
 </para>
 
 @dest: 
@@ -69,7 +68,6 @@ Calculates the absolute value of each element.
 <!-- ##### FUNCTION oil_abs_u8_s8 ##### -->
 <para>
 
-Calculates the absolute value of each element.
 </para>
 
 @dest: 
@@ -82,7 +80,6 @@ Calculates the absolute value of each element.
 <!-- ##### FUNCTION oil_average2_u8 ##### -->
 <para>
 
-Calculates the average of each element in the source arrays.
 </para>
 
 @dest: 
@@ -456,6 +453,90 @@ Calculates the average of each element in the source arrays.
 @s4_1: 
 
 
+<!-- ##### FUNCTION oil_vectoradd_s_s8 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
+<!-- ##### FUNCTION oil_vectoradd_s_u8 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
+<!-- ##### FUNCTION oil_vectoradd_s_s16 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
+<!-- ##### FUNCTION oil_vectoradd_s_u16 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
+<!-- ##### FUNCTION oil_vectoradd_s_f32 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
+<!-- ##### FUNCTION oil_vectoradd_s_f64 ##### -->
+<para>
+
+</para>
+
+@dest: 
+@dstr: 
+@src1: 
+@sstr1: 
+@src2: 
+@sstr2: 
+@n: 
+
+
 <!-- ##### FUNCTION oil_squaresum_f64 ##### -->
 <para>
 
@@ -469,8 +550,6 @@ Calculates the average of each element in the source arrays.
 <!-- ##### FUNCTION oil_sum_f64 ##### -->
 <para>
 
-Sums each element in the source array and places the result in
-the destination array.
 </para>
 
 @dest: 
diff --git a/liboil/jpeg/yuv2rgb_c.c b/liboil/jpeg/yuv2rgb_c.c
index b980067..a219005 100644
--- a/liboil/jpeg/yuv2rgb_c.c
+++ b/liboil/jpeg/yuv2rgb_c.c
@@ -33,10 +33,53 @@
 #include <liboil/liboiltest.h>
 #include "jpeg.h"
 
+/**
+ * oil_yuv2rgbx_u8:
+ * @d_4xn:
+ * @src1: Y component
+ * @src2: U component
+ * @src3: V component
+ * @n:
+ *
+ * Converts YUV pixels to RGB pixels.  Each YUV component is in a
+ * separate source array, and are combined and converted to RGB.
+ *
+ * This function should be replaced by one that makes sense.
+ */
 OIL_DEFINE_CLASS (yuv2rgbx_u8,
     "uint8_t *d_4xn, uint8_t *src1, uint8_t *src2, uint8_t *src3, int n");
+/**
+ * oil_yuv2rgbx_sub2_u8:
+ * @d_4xn:
+ * @src1: Y component
+ * @src2: U component
+ * @src3: V component
+ * @n:
+ *
+ * Converts YUV pixels to RGB pixels.  Each YUV component is in a
+ * separate source array, and are combined and converted to RGB.
+ * The U and V arrays are subsampled by a factor of 2, so only
+ * half of each array is used.
+ *
+ * This function should be replaced by one that makes sense.
+ */
 OIL_DEFINE_CLASS (yuv2rgbx_sub2_u8,
     "uint8_t *d_4xn, uint8_t *src1, uint8_t *src2, uint8_t *src3, int n");
+/**
+ * oil_yuv2rgbx_sub4_u8:
+ * @d_4xn:
+ * @src1: Y component
+ * @src2: U component
+ * @src3: V component
+ * @n:
+ *
+ * Converts YUV pixels to RGB pixels.  Each YUV component is in a
+ * separate source array, and are combined and converted to RGB.
+ * The U and V arrays are subsampled by a factor of 4, so only
+ * a quarter of each array is used.
+ *
+ * This function should be replaced by one that makes sense.
+ */
 OIL_DEFINE_CLASS (yuv2rgbx_sub4_u8,
     "uint8_t *d_4xn, uint8_t *src1, uint8_t *src2, uint8_t *src3, int n");
 
diff --git a/liboil/liboilfunction.c b/liboil/liboilfunction.c
index 24359ba..6b4a0b5 100644
--- a/liboil/liboilfunction.c
+++ b/liboil/liboilfunction.c
@@ -50,9 +50,11 @@ void _oil_cpu_init (void);
 /**
  * oil_init:
  *
- * Initializes liboil.  This function must be called before any
+ * Initialize liboil.  This function must be called before any
  * other liboil function is used.  @oil_init may be called multiple
  * times.
+ *
+ * Since: 0.3.0
  */
 void
 oil_init (void)
@@ -82,8 +84,9 @@ oil_init (void)
 /**
  * oil_init_no_optimize:
  *
- * Identical to @oil_init(), except that the profiling stage is not
- * done.  This function is mainly useful for internal programs.
+ * Initialize liboil similar to @oil_init(), but do not run the
+ * profiling stage.  This function is mainly useful for internal
+ * programs.
  */
 void
 oil_init_no_optimize (void)
@@ -109,7 +112,7 @@ oil_init_no_optimize (void)
 /**
  * oil_optimize_all:
  *
- * Optimizes all function classes.
+ * Optimize all function classes.
  */
 void
 oil_optimize_all (void)
@@ -128,9 +131,9 @@ oil_optimize_all (void)
 
 /**
  * oil_optimize:
- * @class_name: name of function class to optimize
+ * @class_name: a string
  *
- * Optimizes function class given by @class_name.
+ * Optimize the function class that has the name specified by @class_name.
  */
 void
 oil_optimize (const char *class_name)
@@ -159,11 +162,11 @@ oil_class_get_n_classes (void)
 
 /**
  * oil_class_get_by_index:
- * @i: index of function class
+ * @i: index
  *
  * Returns a pointer to the function class with index @i.
  *
- * Returns: a pointer to a function class structure
+ * Returns: an @OilFunctionClass
  */
 OilFunctionClass *
 oil_class_get_by_index (int i)
@@ -175,7 +178,7 @@ oil_class_get_by_index (int i)
 
 /**
  * oil_impl_is_runnable:
- * @impl: a function implementation
+ * @impl: an @OilFunctionImpl
  *
  * Determines whether the function implementation given by @impl
  * can be executed by the current CPU.
diff --git a/liboil/ref/abs.c b/liboil/ref/abs.c
index 6cbfbbd..81a7b5c 100644
--- a/liboil/ref/abs.c
+++ b/liboil/ref/abs.c
@@ -44,15 +44,17 @@ OIL_DEFINE_CLASS (abs_f64_f64, "double *dest, int dstr, double *src, int sstr, i
 #define ABS(x) ((x)>0 ? (x) : -(x))
 
 
-#if 0
-static void
-abs_test (OilFunctionClass *klass, OilFunctionImpl *impl)
-{
-
-
-}
-#endif
-
+/**
+ * oil_abs_u8_s8:
+ * @dest: destination array
+ * @dstr: stride of destination elements
+ * @src: source array
+ * @sstr: stride of source elements
+ * @n: number of elements in arrays
+ *
+ * Calculates the absolute value of each element in the source array
+ * and writes it into the destination array.
+ */
 static void
 abs_u8_s8_ref (uint8_t *dest, int dstr, int8_t *src, int sstr, int n)
 {
@@ -67,6 +69,17 @@ abs_u8_s8_ref (uint8_t *dest, int dstr, int8_t *src, int sstr, int n)
 }
 OIL_DEFINE_IMPL_REF (abs_u8_s8_ref, abs_u8_s8);
 
+/**
+ * oil_abs_u16_s16:
+ * @dest: destination array
+ * @dstr: stride of destination elements
+ * @src: source array
+ * @sstr: stride of source elements
+ * @n: number of elements in arrays
+ *
+ * Calculates the absolute value of each element in the source array
+ * and writes it into the destination array.
+ */
 static void
 abs_u16_s16_ref (uint16_t *dest, int dstr, int16_t *src, int sstr, int n)
 {
@@ -81,6 +94,17 @@ abs_u16_s16_ref (uint16_t *dest, int dstr, int16_t *src, int sstr, int n)
 }
 OIL_DEFINE_IMPL_REF (abs_u16_s16_ref, abs_u16_s16);
 
+/**
+ * oil_abs_u32_s32:
+ * @dest: destination array
+ * @dstr: stride of destination elements
+ * @src: source array
+ * @sstr: stride of source elements
+ * @n: number of elements in arrays
+ *
+ * Calculates the absolute value of each element in the source array
+ * and writes it into the destination array.
+ */
 static void
 abs_u32_s32_ref (uint32_t *dest, int dstr, int32_t *src, int sstr, int n)
 {
@@ -95,6 +119,17 @@ abs_u32_s32_ref (uint32_t *dest, int dstr, int32_t *src, int sstr, int n)
 }
 OIL_DEFINE_IMPL_REF (abs_u32_s32_ref, abs_u32_s32);
 
+/**
+ * oil_abs_f32_f32:
+ * @dest: destination array
+ * @dstr: stride of destination elements
+ * @src: source array
+ * @sstr: stride of source elements
+ * @n: number of elements in arrays
+ *
+ * Calculates the absolute value of each element in the source array
+ * and writes it into the destination array.
+ */
 static void
 abs_f32_f32_ref (float *dest, int dstr, float *src, int sstr, int n)
 {
@@ -107,6 +142,17 @@ abs_f32_f32_ref (float *dest, int dstr, float *src, int sstr, int n)
 
 OIL_DEFINE_IMPL_REF (abs_f32_f32_ref, abs_f32_f32);
 
+/**
+ * oil_abs_f64_f64:
+ * @dest: destination array
+ * @dstr: stride of destination elements
+ * @src: source array
+ * @sstr: stride of source elements
+ * @n: number of elements in arrays
+ *
+ * Calculates the absolute value of each element in the source array
+ * and writes it into the destination array.
+ */
 static void
 abs_f64_f64_ref (double *dest, int dstr, double *src, int sstr, int n)
 {
diff --git a/liboil/ref/argb_paint.c b/liboil/ref/argb_paint.c
index 8227b11..d253ba2 100644
--- a/liboil/ref/argb_paint.c
+++ b/liboil/ref/argb_paint.c
@@ -38,6 +38,18 @@ OIL_DEFINE_CLASS (argb_paint_u8, "uint8_t *i_4xn, uint8_t *s1_4, uint8_t *s2_n,
 #define div255(x) (((x + 128) + ((x + 128)>>8))>>8)
 #define blend(x,y,a) div255((x)*(a) + (y)*(255-(a)))
 
+/**
+ * oil_argb_paint_u8:
+ * @i_4xn: array
+ * @s1_4: source color
+ * @s2_n: source alpha array
+ * @n: number of elements
+ *
+ * Composites source color onto in-place array according to the alpha
+ * array.
+ *
+ * Deprecated.
+ */
 static void
 argb_paint_u8_ref (uint8_t *dest, const uint8_t *color, const uint8_t *alpha, int n)
 {
diff --git a/liboil/ref/ayuv2argb.c b/liboil/ref/ayuv2argb.c
index f65e597..72716a7 100644
--- a/liboil/ref/ayuv2argb.c
+++ b/liboil/ref/ayuv2argb.c
@@ -32,6 +32,19 @@
 #include <liboil/liboil.h>
 #include <liboil/liboilfunction.h>
 
+/**
+ * oil_ayuv2argb_u8:
+ * @d_4xn:
+ * @s_4xn:
+ * @n:
+ *
+ * Converts AYUV pixels to ARGB pixels.  AYUV pixels are in the
+ * JPEG colorspace.  Note that this function doesn't follow normal
+ * liboil pixel conventions.
+ *
+ * (This function should be replaced by one that handles other
+ * conversion factors.)
+ */
 OIL_DEFINE_CLASS (ayuv2argb_u8, "uint8_t *d_4xn, uint8_t *s_4xn, int n");
 
 #define clamp(x,a,b) clamp_lower(clamp_upper(x,b),a)
diff --git a/liboil/ref/composite.c b/liboil/ref/composite.c
index 5f02ad3..26c133b 100644
--- a/liboil/ref/composite.c
+++ b/liboil/ref/composite.c
@@ -39,6 +39,20 @@
 #define COMPOSITE_ADD(d,s) oil_clamp_255((d) + (s))
 #define COMPOSITE_IN(s,m) oil_muldiv_255((s),(m))
 
+/**
+ * SECTION:liboilfuncs-pixel
+ * @short_description: Operations on pixels
+ *
+ * Pixels are 4-element arrays of type uint8_t.  The elements, in
+ * memory order, represent the alpha, red, green, and blue
+ * components respectively.  The color components are premultiplied
+ * with the alpha component.  Liboil functions represent pixels
+ * as the type uint32_t.
+ *
+ * The compositing operators IN, OVER, and ADD are defined the same
+ * as cairo.
+ *
+ */
 static void
 composite_test (OilTest *test)
 {
@@ -80,39 +94,147 @@ composite_test (OilTest *test)
 
 }
 
+/**
+ * oil_composite_in_argb:
+ * @d_n: DEST
+ * @s1_n: SRC
+ * @s2_n: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC IN MASK.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_argb,
     "uint32_t *d_n, uint32_t *s1_n, uint8_t *s2_n, int n",
     composite_test);
+/**
+ * oil_composite_in_argb_const_src:
+ * @d_n: DEST
+ * @s1_1: SRC
+ * @s2_n: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC IN MASK, for a constant
+ * SRC.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_argb_const_src,
     "uint32_t *d_n, uint32_t *s1_1, uint8_t *s2_n, int n",
     composite_test);
+/**
+ * oil_composite_in_argb_const_mask:
+ * @d_n: DEST
+ * @s1_n: SRC
+ * @s2_1: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC IN MASK, for a constant
+ * MASK.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_argb_const_mask,
     "uint32_t *d_n, uint32_t *s1_n, uint8_t *s2_1, int n",
     composite_test);
+/**
+ * oil_composite_over_argb:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC OVER DEST.
+ */
 OIL_DEFINE_CLASS_FULL (composite_over_argb,
     "uint32_t *i_n, uint32_t *s1_n, int n",
     composite_test);
+/**
+ * oil_composite_over_argb_const_src:
+ * @i_n: DEST
+ * @s1_1: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC OVER DEST, for a
+ * constant SRC.
+ */
 OIL_DEFINE_CLASS_FULL (composite_over_argb_const_src,
     "uint32_t *i_n, uint32_t *s1_1, int n",
     composite_test);
+/**
+ * oil_composite_add_argb:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC ADD DEST.
+ */
 OIL_DEFINE_CLASS_FULL (composite_add_argb,
     "uint32_t *i_n, uint32_t *s1_n, int n",
     composite_test);
+/**
+ * oil_composite_add_argb_const_src:
+ * @i_n: DEST
+ * @s1_1: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC ADD DEST, for a
+ * constant SRC.
+ */
 OIL_DEFINE_CLASS_FULL (composite_add_argb_const_src,
     "uint32_t *i_n, uint32_t *s1_1, int n",
     composite_test);
+/**
+ * oil_composite_in_over_argb:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @s2_n: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = (SRC IN MASK) OVER DEST.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_over_argb,
     "uint32_t *i_n, uint32_t *s1_n, uint8_t *s2_n, int n",
     composite_test);
+/**
+ * oil_composite_in_over_argb_const_src:
+ * @i_n: DEST
+ * @s1_1: SRC
+ * @s2_n: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = (SRC IN MASK) OVER DEST,
+ * for a constant SRC.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_over_argb_const_src,
     "uint32_t *i_n, uint32_t *s1_1, uint8_t *s2_n, int n",
     composite_test);
+/**
+ * oil_composite_in_over_argb_const_mask:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @s2_1: MASK
+ * @n:
+ *
+ * Performs the compositing operation DEST = (SRC IN MASK) OVER DEST,
+ * for a constant MASK.
+ */
 OIL_DEFINE_CLASS_FULL (composite_in_over_argb_const_mask,
     "uint32_t *i_n, uint32_t *s1_n, uint8_t *s2_1, int n",
     composite_test);
+/**
+ * oil_composite_over_argb_u8:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC OVER DEST.
+ */
 OIL_DEFINE_CLASS_FULL (composite_over_u8,
     "uint8_t *i_n, uint8_t *s1_n, int n",
     composite_test);
+/**
+ * oil_composite_add_argb_u8:
+ * @i_n: DEST
+ * @s1_n: SRC
+ * @n:
+ *
+ * Performs the compositing operation DEST = SRC ADD DEST.
+ */
 OIL_DEFINE_CLASS_FULL (composite_add_u8,
     "uint8_t *i_n, uint8_t *s1_n, int n",
     composite_test);
diff --git a/liboil/ref/resample.c b/liboil/ref/resample.c
index 831f93f..acefb1c 100644
--- a/liboil/ref/resample.c
+++ b/liboil/ref/resample.c
@@ -35,6 +35,15 @@
 #include <liboil/liboilrandom.h>
 
 
+/**
+ * oil_resample_linear_u8:
+ * @d_n:
+ * @s_2xn:
+ * @n:
+ * @i_2:
+ *
+ * Linearly resamples a row of pixels.  FIXME.
+ */
 static void
 resample_linear_u8_test (OilTest *test)
 {
@@ -48,6 +57,15 @@ OIL_DEFINE_CLASS_FULL (resample_linear_u8,
     "uint8_t *d_n, uint8_t *s_2xn, int n, uint32_t *i_2",
     resample_linear_u8_test);
 
+/**
+ * oil_resample_linear_argb:
+ * @d_n:
+ * @s_2xn:
+ * @n:
+ * @i_2:
+ *
+ * Linearly resamples a row of pixels.  FIXME.
+ */
 static void
 resample_linear_argb_test (OilTest *test)
 {
@@ -110,6 +128,23 @@ resample_linear_argb_ref (uint32_t *d, uint32_t *s, int n, uint32_t *in)
 OIL_DEFINE_IMPL_REF (resample_linear_argb_ref, resample_linear_argb);
 
 
+/**
+ * oil_merge_linear_u8:
+ * @d_n:
+ * @s_n:
+ * @s2_n:
+ * @s3_1:
+ * @n:
+ *
+ * Linearly interpolate the @s_n and @s2_n arrays using the scale
+ * factor in @s3_1.  Valid values of @s3_1 range from 0 to 256
+ * inclusive.  A value of 0 indicates weights of 1.0 and 0.0 for
+ * the s_n and s2_n arrays respectively.  A value of 256 indicates
+ * weights of 0.0 and 1.0 respectively.
+ *
+ * This function is not intended for alpha blending; use one of the
+ * composite functions instead.
+ */
 static void
 merge_linear_argb_test (OilTest *test)
 {
diff --git a/liboil/ref/rgb.c b/liboil/ref/rgb.c
index 5410162..280361f 100644
--- a/liboil/ref/rgb.c
+++ b/liboil/ref/rgb.c
@@ -31,7 +31,25 @@
 
 #include <liboil/liboilfunction.h>
 
+/**
+ * oil_rgb2bgr:
+ * @d_3xn:
+ * @s_3xn:
+ * @n:
+ *
+ * Converts arrays of 24-bit RGB pixels from RGBRGBRGB ordering to
+ * BGRBGRBGR ordering (and vice-versa).
+ */
 OIL_DEFINE_CLASS (rgb2bgr, "uint8_t *d_3xn, uint8_t* s_3xn, int n");
+/**
+ * oil_rgb2rgba:
+ * @d_4xn:
+ * @s_3xn:
+ * @n:
+ *
+ * Converts arrays of 24-bit RGB pixels in RGBRGBRGB memory order
+ * to 32-bit RGBA pixels in RGBARGBA order.
+ */
 OIL_DEFINE_CLASS (rgb2rgba, "uint8_t *d_4xn, uint8_t* s_3xn, int n");
 
 static void
diff --git a/liboil/ref/yuv.c b/liboil/ref/yuv.c
index e53304d..37da1d5 100644
--- a/liboil/ref/yuv.c
+++ b/liboil/ref/yuv.c
@@ -41,12 +41,66 @@
 #define AYUV_V(color) (((color)>>0)&0xff)
 
 
+/**
+ * oil_yuyv2ayuv:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in YUYV format to AYUV.  Note that only approximately
+ * half of the source array is used.  Alpha values are set to 255.
+ */
 OIL_DEFINE_CLASS (yuyv2ayuv, "uint32_t *d_n, uint32_t *s_n, int n");
+/**
+ * oil_yvyu2ayuv:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in YVYU format to AYUV.  Note that only approximately
+ * half of the source array is used.  Alpha values are set to 255.
+ */
 OIL_DEFINE_CLASS (yvyu2ayuv, "uint32_t *d_n, uint32_t *s_n, int n");
+/**
+ * oil_uyvy2ayuv:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in UYVY format to AYUV.  Note that only approximately
+ * half of the source array is used.  Alpha values are set to 255.
+ */
 OIL_DEFINE_CLASS (uyvy2ayuv, "uint32_t *d_n, uint32_t *s_n, int n");
 
+/**
+ * oil_ayuv2yuyv:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in AYUV format to YUYV.  Note that only approximately
+ * half of the destination array is written.  Alpha values are ignored.
+ */
 OIL_DEFINE_CLASS (ayuv2yuyv, "uint32_t *d_n, uint32_t *s_n, int n");
+/**
+ * oil_ayuv2yvyu:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in AYUV format to YVYU.  Note that only approximately
+ * half of the destination array is written.  Alpha values are ignored.
+ */
 OIL_DEFINE_CLASS (ayuv2yvyu, "uint32_t *d_n, uint32_t *s_n, int n");
+/**
+ * oil_ayuv2uyvy:
+ * @d_n:
+ * @s_n:
+ * n:
+ *
+ * Converts pixels in AYUV format to UYVY.  Note that only approximately
+ * half of the destination array is written.  Alpha values are ignored.
+ */
 OIL_DEFINE_CLASS (ayuv2uyvy, "uint32_t *d_n, uint32_t *s_n, int n");