[gdk-pixbuf] Documentation: Migrate from old tmpl files.

[Jon Nordby <jonnor src gnome org>]

commit 80ad1d60b40f73b5b1b78e84affed2e0f207f5ae
Author: Jon Nordby <jononor gmail com>
Date:   Tue Mar 1 00:20:55 2011 +0000

    Documentation: Migrate from old tmpl files.
    
    This puts all the docs that existed in tmpl files when
    gdk-pixbuf was moved out of gtk into inline comments.
    
    Fixes: https://bugzilla.gnome.org/show_bug.cgi?id=635643

 contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-drawable.c |   16 ++
 contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-render.c   |   13 ++
 contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib.c          |   15 ++
 contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c       |   12 ++
 contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.h       |   25 +++-
 gdk-pixbuf/gdk-pixbuf-animation.c                  |   16 ++
 gdk-pixbuf/gdk-pixbuf-animation.h                  |   40 +++++
 gdk-pixbuf/gdk-pixbuf-core.h                       |  179 +++++++++++++++++++-
 gdk-pixbuf/gdk-pixbuf-features.h.in                |   79 +++++++++
 gdk-pixbuf/gdk-pixbuf-io.c                         |   87 ++++++++++
 gdk-pixbuf/gdk-pixbuf-io.h                         |  170 +++++++++++++++++++
 gdk-pixbuf/gdk-pixbuf-loader.c                     |   63 +++++++
 gdk-pixbuf/gdk-pixbuf-loader.h                     |    7 +-
 gdk-pixbuf/gdk-pixbuf-scale.c                      |   72 ++++++++
 gdk-pixbuf/gdk-pixbuf-simple-anim.h                |    5 +
 gdk-pixbuf/gdk-pixbuf-transform.h                  |   43 +++++-
 gdk-pixbuf/gdk-pixbuf-util.c                       |   11 ++
 gdk-pixbuf/gdk-pixbuf.c                            |   71 ++++++++
 gdk-pixbuf/gdk-pixdata.c                           |   13 ++
 19 files changed, 925 insertions(+), 12 deletions(-)
---
diff --git a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-drawable.c b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-drawable.c
index ea6d8c2..5daec9a 100644
--- a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-drawable.c
+++ b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-drawable.c
@@ -33,6 +33,22 @@
 #include <X11/Xlib.h>
 #include <X11/Xutil.h>
 
+/**
+ * SECTION:gdk-pixbuf-xlib-from-drawables
+ * @Short_description: Getting parts of an X drawable's image data into a pixbuf.
+ * @Title: X Drawables to Pixbufs
+ * 
+ * The functions in this section allow you to take the image data
+ * from an X drawable and dump it into a #GdkPixbuf.  This can be
+ * used for screenshots and other special effects.  Note that these
+ * operations can be expensive, since the image data has to be
+ * transferred from the X server to the client program and converted.
+ * 
+ * 
+ * These functions are analogous to those for the GDK version of
+ * &gdk-pixbuf;.
+ */
+
 #if (G_BYTE_ORDER == G_LITTLE_ENDIAN)
 #define LITTLE
 #endif
diff --git a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-render.c b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-render.c
index ea64f30..f6f264a 100644
--- a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-render.c
+++ b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib-render.c
@@ -25,6 +25,19 @@
 #include "config.h"
 #include "gdk-pixbuf-xlib-private.h"
 
+/**
+ * SECTION:gdk-pixbuf-xlib-rendering
+ * @Short_description: Rendering a pixbuf to an X drawable.
+ * @Title: Xlib Rendering
+ * 
+ * The &gdk-pixbuf; Xlib library provides several convenience
+ * functions to render pixbufs to X drawables.  It uses XlibRGB to
+ * render the image data.
+ * 
+ * 
+ * These functions are analogous to those for the GDK version of
+ * &gdk-pixbuf;.
+ */
 
 
 /**
diff --git a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib.c b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib.c
index e2d17e3..ceb9d1e 100644
--- a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib.c
+++ b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlib.c
@@ -22,6 +22,21 @@
 #include <X11/Xlib.h>
 #include "gdk-pixbuf-xlib-private.h"
 
+/**
+ * SECTION:gdk-pixbuf-xlib-init
+ * @Short_description: Initializing the &gdk-pixbuf; Xlib library.
+ * @Title: &gdk-pixbuf; Xlib initialization
+ * @See_also:    XlibRGB
+ * 
+ * In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
+ * package provides a small library that lets Xlib-only applications
+ * use #GdkPixbuf structures and render them to X drawables.  The
+ * functions in this section are used to initialize the &gdk-pixbuf;
+ * Xlib library.  This library must be initialized near the beginning
+ * of the program or before calling any of the other &gdk-pixbuf;
+ * Xlib functions.
+ */
+
 Display *gdk_pixbuf_dpy = NULL;
 int gdk_pixbuf_screen = -1;
 
diff --git a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c
index 701f34a..ff749c5 100644
--- a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c
+++ b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.c
@@ -47,6 +47,18 @@
  * Shawn T. Amundson    <amundson gtk org>
 */
 
+/**
+ * SECTION:gdk-pixbuf-xlib-rgb
+ * @Short_description: Rendering RGB buffers to X drawables.
+ * @Title: XlibRGB
+ * @See_also:    GdkRGB
+ * 
+ * The XlibRGB set of functions is a port of the #GdkRGB library to
+ * use plain Xlib and X drawables.  You can use these functions to
+ * render RGB buffers into drawables very quickly with high-quality
+ * dithering.
+ */
+
 #if HAVE_CONFIG_H
 #  include <config.h>
 #  if STDC_HEADERS
diff --git a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.h b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.h
index 9433aea..f838ea8 100644
--- a/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.h
+++ b/contrib/gdk-pixbuf-xlib/gdk-pixbuf-xlibrgb.h
@@ -58,8 +58,14 @@ G_BEGIN_DECLS
 #include <X11/Xlib.h>
 #include <X11/Xutil.h>
 
+/**
+ * XlibRgbCmap:
+ * @colors: FIXME.
+ * @lut: FIXME.
+ * 
+ *     FIXME: Describe this.
+ */
 typedef struct _XlibRgbCmap XlibRgbCmap;
-
 struct _XlibRgbCmap {
   unsigned int colors[256];
   unsigned char lut[256]; /* for 8-bit modes */
@@ -79,6 +85,23 @@ xlib_rgb_gc_set_foreground (GC gc, guint32 rgb);
 void
 xlib_rgb_gc_set_background (GC gc, guint32 rgb);
 
+/**
+ * XlibRgbDither:
+ * @XLIB_RGB_DITHER_NONE: Specifies no dithering.
+ * @XLIB_RGB_DITHER_NORMAL: Specifies dithering only on pseudocolor
+ *  displays.
+ * @XLIB_RGB_DITHER_MAX: Specifies dithering on high color displays.
+ * 
+ * These values are used to specify which dithering method should be
+ * used.  <symbol>XLIB_RGB_DITHER_NONE</symbol> will use no dithering
+ * and simply map the colors in an RGB buffer to the closest colors
+ * that the display can provide.
+ * <symbol>XLIB_RGB_DITHER_NORMAL</symbol> will provide dithering
+ * only on pseudocolor displays.
+ * <symbol>XLIB_RGB_DITHER_MAX</symbol> will provide dithering on
+ * pseudocolor and 16-bit truecolor or &ldquo;high color&rdquo;
+ * displays.
+ */
 typedef enum
 {
   XLIB_RGB_DITHER_NONE,
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c
index efb9b3d..ff22799 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.c
+++ b/gdk-pixbuf/gdk-pixbuf-animation.c
@@ -29,6 +29,22 @@
 
 #include <glib/gstdio.h>
 
+/**
+ * SECTION:animation
+ * @Short_description: Animated images.
+ * @Title: Animations
+ * @See_also: #GdkPixbufLoader.
+ * 
+ * The &gdk-pixbuf; library provides a simple mechanism to load and represent
+ * animations. An animation is conceptually a series of frames to be displayed
+ * over time. Each frame is the same size. The animation may not be represented
+ * as a series of frames internally; for example, it may be stored as a 
+ * sprite and instructions for moving the sprite around a background. To display 
+ * an animation you don't need to understand its representation, however; you just
+ * ask &gdk-pixbuf; what should be displayed at a given point in time. 
+ * 
+ */
+
 typedef struct _GdkPixbufNonAnim GdkPixbufNonAnim;
 typedef struct _GdkPixbufNonAnimClass GdkPixbufNonAnimClass;
 
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.h b/gdk-pixbuf/gdk-pixbuf-animation.h
index 32757ee..e32a242 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.h
+++ b/gdk-pixbuf/gdk-pixbuf-animation.h
@@ -38,7 +38,20 @@ G_BEGIN_DECLS
 
 /* Animation support */
 
+/**
+ * GdkPixbufAnimation:
+ * 
+ * An opaque struct representing an animation.
+ */
 typedef struct _GdkPixbufAnimation GdkPixbufAnimation;
+
+
+/**
+ * GdkPixbufAnimationIter:
+ * 
+ * An opaque struct representing an iterator which points to a
+ * certain position in an animation.
+ */
 typedef struct _GdkPixbufAnimationIter GdkPixbufAnimationIter;
 
 #define GDK_TYPE_PIXBUF_ANIMATION              (gdk_pixbuf_animation_get_type ())
@@ -82,6 +95,18 @@ gboolean                gdk_pixbuf_animation_iter_advance                    (Gd
 
 
 
+/**
+ * GdkPixbufAnimationClass:
+ * @parent_class: the parent class
+ * @is_static_image: returns whether the given animation is just a static image.
+ * @get_static_image: returns a static image representing the given animation.
+ * @get_size: fills @width and @height with the frame size of the animation.
+ * @get_iter: returns an iterator for the given animation.
+ * 
+ * Modules supporting animations must derive a type from 
+ * #GdkPixbufAnimation, providing suitable implementations of the 
+ * virtual functions.
+ */
 typedef struct _GdkPixbufAnimationClass GdkPixbufAnimationClass;
 
 #define GDK_PIXBUF_ANIMATION_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), GDK_TYPE_PIXBUF_ANIMATION, GdkPixbufAnimationClass))
@@ -114,6 +139,21 @@ struct _GdkPixbufAnimationClass {
 
 
 
+/**
+ * GdkPixbufAnimationIterClass:
+ * @parent_class: the parent class
+ * @get_delay_time: returns the time in milliseconds that the current frame 
+ *  should be shown.
+ * @get_pixbuf: returns the current frame.
+ * @on_currently_loading_frame: returns whether the current frame of @iter is 
+ *  being loaded.
+ * @advance: advances the iterator to @current_time, possibly changing the 
+ *  current frame.
+ * 
+ * Modules supporting animations must derive a type from 
+ * #GdkPixbufAnimationIter, providing suitable implementations of the 
+ * virtual functions.
+ */
 typedef struct _GdkPixbufAnimationIterClass GdkPixbufAnimationIterClass;
 
 #define GDK_PIXBUF_ANIMATION_ITER_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), GDK_TYPE_PIXBUF_ANIMATION_ITER, GdkPixbufAnimationIterClass))
diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h
index 13cec1e..607e76c 100644
--- a/gdk-pixbuf/gdk-pixbuf-core.h
+++ b/gdk-pixbuf/gdk-pixbuf-core.h
@@ -36,15 +36,122 @@
 
 G_BEGIN_DECLS
 
-/* Alpha compositing mode */
+/**
+ * SECTION:gdk-pixbuf
+ * @Short_description: Information that describes an image.
+ * @Title: The GdkPixbuf Structure
+ * 
+ * 
+ * The #GdkPixbuf structure contains
+ * information that describes an image in memory.
+ * 
+ * 
+ * <section id="image-data">
+ * <title>Image Data</title>
+ * <para>
+ * Image data in a pixbuf is stored in memory in uncompressed,
+ * packed format.  Rows in the image are stored top to bottom, and
+ * in each row pixels are stored from left to right.  There may be
+ * padding at the end of a row.  The "rowstride" value of a pixbuf,
+ * as returned by gdk_pixbuf_get_rowstride(), indicates the number
+ * of bytes between rows.
+ * 
+ * 
+ * <example id="put-pixel">
+ * <title>put_pixel(<!-- -->) example</title>
+ * <para>
+ * 
+ * The following code illustrates a simple put_pixel(<!-- -->)
+ * function for RGB pixbufs with 8 bits per channel with an alpha
+ * channel.  It is not included in the gdk-pixbuf library for
+ * performance reasons; rather than making several function calls
+ * for each pixel, your own code can take shortcuts.
+ * 
+ * 
+ * <programlisting>
+ * static void
+ * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
+ * {
+ *   int width, height, rowstride, n_channels;
+ *   guchar *pixels, *p;
+ * 
+ *   n_channels = gdk_pixbuf_get_n_channels (pixbuf);
+ * 
+ *   g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
+ *   g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
+ *   g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
+ *   g_assert (n_channels == 4);
+ * 
+ *   width = gdk_pixbuf_get_width (pixbuf);
+ *   height = gdk_pixbuf_get_height (pixbuf);
+ * 
+ *   g_assert (x >= 0 && x < width);
+ *   g_assert (y >= 0 && y < height);
+ * 
+ *   rowstride = gdk_pixbuf_get_rowstride (pixbuf);
+ *   pixels = gdk_pixbuf_get_pixels (pixbuf);
+ * 
+ *   p = pixels + y * rowstride + x * n_channels;
+ *   p[0] = red;
+ *   p[1] = green;
+ *   p[2] = blue;
+ *   p[3] = alpha;
+ * }
+ * </programlisting>
+ * 
+ * This function will not work for pixbufs with images that are
+ * other than 8 bits per sample or channel, but it will work for
+ * most of the pixbufs that GTK+ uses.
+ * </para>
+ * </example>
+ * 
+ * <note>
+ * If you are doing memcpy() of raw pixbuf data, note that the
+ * last row in the pixbuf may not be as wide as the full
+ * rowstride, but rather just as wide as the pixel data needs to
+ * be.  That is, it is unsafe to do <literal>memcpy (dest,
+ * pixels, rowstride * height)</literal> to copy a whole pixbuf.
+ * Use gdk_pixbuf_copy() instead, or compute the width in bytes
+ * of the last row as <literal>width * ((n_channels *
+ * bits_per_sample + 7) / 8)</literal>.
+ * </note>
+ * </para>
+ * </section>
+ */
+
+
+/**
+ * GdkPixbufAlphaMode:
+ * @GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
+ *  will be created and used to draw the image.  Pixels below 0.5 opacity
+ *  will be considered fully transparent, and all others will be
+ *  considered fully opaque.
+ * @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
+ *  In the future it will do full alpha compositing.
+ * 
+ * These values can be passed to
+ * gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
+ * channel of an image should be handled.  This function can create a
+ * bilevel clipping mask (black and white) and use it while painting
+ * the image.  In the future, when the X Window System gets an alpha
+ * channel extension, it will be possible to do full alpha
+ * compositing onto arbitrary drawables.  For now both cases fall
+ * back to a bilevel clipping mask.
+ */
 typedef enum
 {
         GDK_PIXBUF_ALPHA_BILEVEL,
         GDK_PIXBUF_ALPHA_FULL
 } GdkPixbufAlphaMode;
 
-/* Color spaces; right now only RGB is supported.
- * Note that these values are encoded in inline pixbufs
+/**
+ * GdkColorspace:
+ * @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
+ * 
+ * This enumeration defines the color spaces that are supported by
+ * the &gdk-pixbuf; library.  Currently only RGB is supported.
+ */
+/* Note that these values are encoded in inline pixbufs
  * as ints, so don't reorder them
  */
 typedef enum {
@@ -52,6 +159,16 @@ typedef enum {
 } GdkColorspace;
 
 /* All of these are opaque structures */
+
+/**
+ * GdkPixbuf:
+ * 
+ * This is the main structure in the &gdk-pixbuf; library.  It is
+ * used to represent images.  It contains information about the
+ * image's pixel data, its color space, bits per sample, width and
+ * height, and the rowstride (the number of bytes between the start of
+ * one row and the start of the next). 
+ */
 typedef struct _GdkPixbuf GdkPixbuf;
 
 #define GDK_TYPE_PIXBUF              (gdk_pixbuf_get_type ())
@@ -59,11 +176,43 @@ typedef struct _GdkPixbuf GdkPixbuf;
 #define GDK_IS_PIXBUF(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDK_TYPE_PIXBUF))
 
 
-/* Handler that must free the pixel array */
+/**
+ * GdkPixbufDestroyNotify:
+ * @pixels: The pixel array of the pixbuf that is being finalized.
+ * @data: User closure data.
+ * 
+ * A function of this type is responsible for freeing the pixel array
+ * of a pixbuf.  The gdk_pixbuf_new_from_data() function lets you
+ * pass in a pre-allocated pixel array so that a pixbuf can be
+ * created from it; in this case you will need to pass in a function
+ * of #GdkPixbufDestroyNotify so that the pixel data can be freed
+ * when the pixbuf is finalized.
+ */
 typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
 
+/**
+ * GDK_PIXBUF_ERROR:
+ * 
+ * Error domain used for pixbuf operations. Indicates that the error code
+ * will be in the #GdkPixbufError enumeration. See #GError for
+ * information on error domains and error codes.
+ */
 #define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
 
+/**
+ * GdkPixbufError:
+ * @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
+ * @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
+ * @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
+ * @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
+ * @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
+ *  given operation on the type of image at hand.
+ * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
+ * 
+ * An error code in the #GDK_PIXBUF_ERROR domain. Many &gdk-pixbuf;
+ * operations can cause errors in this domain, or in the #G_FILE_ERROR
+ * domain.
+ */
 typedef enum {
         /* image data hosed */
         GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
@@ -182,13 +331,25 @@ gboolean gdk_pixbuf_savev          (GdkPixbuf  *pixbuf,
 
 /* Saving to a callback function */
 
+
 /**
  * GdkPixbufSaveFunc:
- * @buf:
- * @count:
- * @error: (out):
- * @data: (closure):
- **/
+ * @buf: bytes to be written.
+ * @count: number of bytes in @buf. 
+ * @error: (out): A location to return an error.
+ * @data: (closure): user data passed to gdk_pixbuf_save_to_callback(). 
+ * 
+ * Specifies the type of the function passed to
+ * gdk_pixbuf_save_to_callback().  It is called once for each block of
+ * bytes that is "written" by gdk_pixbuf_save_to_callback().  If
+ * successful it should return %TRUE.  If an error occurs it should set
+ * @error and return %FALSE, in which case gdk_pixbuf_save_to_callback()
+ * will fail with the same error.
+ * 
+ * Since: 2.4
+ * Returns: %TRUE if successful, %FALSE (with @error set) if failed.
+ */
+
 typedef gboolean (*GdkPixbufSaveFunc)   (const gchar *buf,
 					 gsize count,
 					 GError **error,
diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in
index ea1674d..721795a 100644
--- a/gdk-pixbuf/gdk-pixbuf-features.h.in
+++ b/gdk-pixbuf/gdk-pixbuf-features.h.in
@@ -5,6 +5,42 @@
 #ifndef GDK_PIXBUF_FEATURES_H
 #define GDK_PIXBUF_FEATURES_H 1
 
+/**
+ * SECTION:initialization_versions
+ * @Short_description: 
+Library version numbers.
+ * @Title: Initialization and Versions
+ * 
+ * These macros and variables let you check the version of &gdk-pixbuf;
+ * you're linking against.
+ */
+
+/**
+ * GDK_PIXBUF_MAJOR:
+ * 
+ * Major version of &gdk-pixbuf; library, that is the first "0" in
+ * "0.8.0" for example.
+ */
+/**
+ * GDK_PIXBUF_MINOR:
+ * 
+ * Minor version of &gdk-pixbuf; library, that is the "8" in
+ * "0.8.0" for example.
+ */
+/**
+ * GDK_PIXBUF_MICRO:
+ * 
+ * Micro version of &gdk-pixbuf; library, that is the last "0" in
+ * "0.8.0" for example.
+ */
+/**
+ * GDK_PIXBUF_VERSION:
+ * 
+ * Contains the full version of the &gdk-pixbuf; header as a string.
+ * This is the version being compiled against; contrast with
+ * #gdk_pixbuf_version.
+ */
+
 #define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@)
 #define GDK_PIXBUF_MINOR (@GDK_PIXBUF_MINOR@)
 #define GDK_PIXBUF_MICRO (@GDK_PIXBUF_MICRO@)
@@ -31,6 +67,49 @@
 #  define GDK_PIXBUF_VAR extern
 #endif /* !G_PLATFORM_WIN32 */
 
+/**
+ * gdk_pixbuf_major_version:
+ * 
+ * The major version number of the &gdk-pixbuf; library.  (e.g. in 
+ * &gdk-pixbuf; version 1.2.5 this is 1.) 
+ * 
+ * 
+ * This variable is in the library, so represents the
+ * &gdk-pixbuf; library you have linked against. Contrast with the
+ * #GDK_PIXBUF_MAJOR macro, which represents the major version of the
+ * &gdk-pixbuf; headers you have included.
+ */
+/**
+ * gdk_pixbuf_minor_version:
+ * 
+ * The minor version number of the &gdk-pixbuf; library.  (e.g. in 
+ * &gdk-pixbuf; version 1.2.5 this is 2.) 
+ * 
+ * 
+ * This variable is in the library, so represents the
+ * &gdk-pixbuf; library you have linked against. Contrast with the
+ * #GDK_PIXBUF_MINOR macro, which represents the minor version of the
+ * &gdk-pixbuf; headers you have included.
+ */
+/**
+ * gdk_pixbuf_micro_version:
+ * 
+ * The micro version number of the &gdk-pixbuf; library.  (e.g. in 
+ * &gdk-pixbuf; version 1.2.5 this is 5.) 
+ * 
+ * 
+ * This variable is in the library, so represents the
+ * &gdk-pixbuf; library you have linked against. Contrast with the
+ * #GDK_PIXBUF_MICRO macro, which represents the micro version of the
+ * &gdk-pixbuf; headers you have included.
+ */
+/**
+ * gdk_pixbuf_version:
+ * 
+ * Contains the full version of the &gdk-pixbuf; library as a string.
+ * This is the version currently in use by a running program.
+ */
+
 GDK_PIXBUF_VAR const guint gdk_pixbuf_major_version;
 GDK_PIXBUF_VAR const guint gdk_pixbuf_minor_version;
 GDK_PIXBUF_VAR const guint gdk_pixbuf_micro_version;
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index b6eb4ea..3b75f73 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -49,6 +49,93 @@
 #define SNIFF_BUFFER_SIZE 4096
 #define LOAD_BUFFER_SIZE 65536
 
+/**
+ * SECTION:file-loading
+ * @Short_description: Loading a pixbuf from a file.
+ * @Title: File Loading
+ * @See_also: #GdkPixbufLoader.
+ * 
+ * The &gdk-pixbuf; library provides a simple mechanism for loading
+ * an image from a file in synchronous fashion.  This means that the
+ * library takes control of the application while the file is being
+ * loaded; from the user's point of view, the application will block
+ * until the image is done loading.
+ * 
+ * 
+ * This interface can be used by applications in which blocking is
+ * acceptable while an image is being loaded.  It can also be used to
+ * load small images in general.  Applications that need progressive
+ * loading can use the #GdkPixbufLoader functionality instead.
+ */
+
+/**
+ * SECTION:file-saving
+ * @Short_description: Saving a pixbuf to a file.
+ * @Title: File saving
+ * 
+ * These functions allow to save a #GdkPixbuf in a number of 
+ * file formats. The formatted data can be written to a file
+ * or to a memory buffer. &gdk-pixbuf; can also call a user-defined
+ * callback on the data, which allows to e.g. write the image 
+ * to a socket or store it in a database.
+ */
+
+/**
+ * SECTION:module_interface
+ * @Short_description: Extending &gdk-pixbuf;
+ * @Title: Module Interface
+ * 
+ * If &gdk-pixbuf; has been compiled with GModule support, it can be extended by
+ * modules which can load (and perhaps also save) new image and animation
+ * formats. Each loadable module must export a
+ * #GdkPixbufModuleFillInfoFunc function named <function>fill_info</function> and
+ * a #GdkPixbufModuleFillVtableFunc function named
+ * <function>fill_vtable</function>.
+ * 
+ * 
+ * In order to make format-checking work before actually loading the modules
+ * (which may require dlopening image libraries), modules export their 
+ * signatures (and other information) via the <function>fill_info</function>
+ * function. An external utility, <command>gdk-pixbuf-query-loaders</command>, 
+ * uses this to create a text file containing a list of all available loaders and 
+ * their signatures. This file is then read at runtime by &gdk-pixbuf; to obtain
+ * the list of available loaders and their signatures. 
+ * 
+ * 
+ * Modules may only implement a subset of the functionality available via
+ * #GdkPixbufModule. If a particular functionality is not implemented, the
+ * <function>fill_vtable</function> function will simply not set the corresponding
+ * function pointers of the #GdkPixbufModule structure. If a module supports
+ * incremental loading (i.e. provides #begin_load, #stop_load and
+ * #load_increment), it doesn't have to implement #load, since &gdk-pixbuf; can 
+ * supply a generic #load implementation wrapping the incremental loading. 
+ * 
+ * 
+ * Installing a module is a two-step process:
+ * <itemizedlist>
+ * <listitem><para>copy the module file(s) to the loader directory (normally
+ * <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>,
+ * unless overridden by the environment variable
+ * <envar>GDK_PIXBUF_MODULEDIR</envar>) 
+ * </para></listitem>
+ * <listitem><para>call <command>gdk-pixbuf-query-loaders</command> to update the
+ * module file (normally
+ * <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>,
+ * unless overridden by the environment variable
+ * <envar>GDK_PIXBUF_MODULE_FILE</envar>)
+ * </para></listitem>
+ * </itemizedlist>
+ * 
+ * 
+ * The &gdk-pixbuf; interfaces needed for implementing modules are contained in 
+ * <filename>gdk-pixbuf-io.h</filename> (and
+ * <filename>gdk-pixbuf-animation.h</filename> if the module supports animations).
+ * They are not covered by the same stability guarantees as the regular 
+ * &gdk-pixbuf; API. To underline this fact, they are protected by 
+ * <literal>#ifdef GDK_PIXBUF_ENABLE_BACKEND</literal>.
+ */
+
+
 #ifndef GDK_PIXBUF_USE_GIO_MIME 
 static gint 
 format_check (GdkPixbufModule *module, guchar *buffer, int size)
diff --git a/gdk-pixbuf/gdk-pixbuf-io.h b/gdk-pixbuf/gdk-pixbuf-io.h
index 5132758..41a99e4 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.h
+++ b/gdk-pixbuf/gdk-pixbuf-io.h
@@ -68,13 +68,69 @@ void             gdk_pixbuf_format_free (GdkPixbufFormat       *format);
 
 
 
+/**
+ * GdkPixbufModuleSizeFunc:
+ * @width: pointer to a location containing the current image width
+ * @height: pointer to a location containing the current image height
+ * @user_data: the loader.
+ * 
+ * Defines the type of the function that gets called once the size 
+ * of the loaded image is known.
+ * 
+ * The function is expected to set @width and @height to the desired
+ * size to which the image should be scaled. If a module has no efficient 
+ * way to achieve the desired scaling during the loading of the image, it may
+ * either ignore the size request, or only approximate it -- &gdk-pixbuf; will
+ * then perform the required scaling on the completely loaded image. 
+ * 
+ * If the function sets @width or @height to zero, the module should interpret
+ * this as a hint that it will be closed soon and shouldn't allocate further 
+ * resources. This convention is used to implement gdk_pixbuf_get_file_info()
+ * efficiently.
+ * 
+ * Since: 2.2
+ */
 typedef void (* GdkPixbufModuleSizeFunc)           (gint *width, 
 						    gint *height, 
 						    gpointer user_data);
 
+/**
+ * GdkPixbufModulePreparedFunc:
+ * @pixbuf: the #GdkPixbuf that is currently being loaded.
+ * @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL.
+ * @user_data: the loader.
+ * 
+ * Defines the type of the function that gets called once the initial 
+ * setup of @pixbuf is done.
+ * 
+ * #GdkPixbufLoader uses a function of this type to emit the 
+ * "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>"
+ * signal.
+ * 
+ * Since: 2.2
+ */
 typedef void (* GdkPixbufModulePreparedFunc) (GdkPixbuf          *pixbuf,
 					      GdkPixbufAnimation *anim,
 					      gpointer            user_data);
+
+/**
+ * GdkPixbufModuleUpdatedFunc:
+ * @pixbuf: the #GdkPixbuf that is currently being loaded.
+ * @x: the X origin of the updated area.
+ * @y: the Y origin of the updated area.
+ * @width: the width of the updated area.
+ * @height: the height of the updated area.
+ * @user_data: the loader.
+ * 
+ * Defines the type of the function that gets called every time a region
+ * of @pixbuf is updated.
+ * 
+ * #GdkPixbufLoader uses a function of this type to emit the 
+ * "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>"
+ * signal.
+ * 
+ * Since: 2.2
+ */
 typedef void (* GdkPixbufModuleUpdatedFunc)  (GdkPixbuf *pixbuf,
 					      int        x,
 					      int        y,
@@ -82,6 +138,43 @@ typedef void (* GdkPixbufModuleUpdatedFunc)  (GdkPixbuf *pixbuf,
 					      int        height,
 					      gpointer   user_data);
 
+/**
+ * GdkPixbufModulePattern:
+ * @prefix: the prefix for this pattern
+ * @mask: mask containing bytes which modify how the prefix is matched against
+ *  test data
+ * @relevance: relevance of this pattern
+ * 
+ * The signature of a module is a set of prefixes. Prefixes are encoded as
+ * pairs of ordinary strings, where the second string, called the mask, if 
+ * not %NULL, must be of the same length as the first one and may contain 
+ * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, 
+ * not matched, "don't-care"-bytes, zeros and non-zeros. 
+ * Each prefix has an associated integer that describes the relevance of 
+ * the prefix, with 0 meaning a mismatch and 100 a "perfect match".
+ * 
+ * Starting with &gdk-pixbuf; 2.8, the first byte of the mask may be '*', 
+ * indicating an unanchored pattern that matches not only at the beginning, 
+ * but also in the middle. Versions prior to 2.8 will interpret the '*'
+ * like an 'x'. 
+ * 
+ * The signature of a module is stored as an array of 
+ * #GdkPixbufModulePattern<!-- -->s. The array is terminated by a pattern
+ * where the @prefix is %NULL.
+ * 
+ * 
+ * <informalexample><programlisting>
+ * GdkPixbufModulePattern *signature[] = {
+ *   { "abcdx", " !x z", 100 },
+ *   { "bla", NULL,  90 },
+ *   { NULL, NULL, 0 }
+ * };
+ * </programlisting>
+ * The example matches e.g. "auud\0" with relevance 100, and "blau" with 
+ * relevance 90.</informalexample>
+ * 
+ * Since: 2.2
+ */
 typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern;
 struct _GdkPixbufModulePattern {
 	char *prefix;
@@ -89,6 +182,30 @@ struct _GdkPixbufModulePattern {
 	int relevance;
 };
 
+/**
+ * GdkPixbufModule:
+ * @module_name: the name of the module, usually the same as the
+ *  usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
+ * @module_path: the path from which the module is loaded.
+ * @module: the loaded #GModule.
+ * @info: a #GdkPixbufFormat holding information about the module.
+ * @load: loads an image from a file.
+ * @load_xpm_data: loads an image from data in memory.
+ * @begin_load: begins an incremental load.
+ * @stop_load: stops an incremental load.
+ * @load_increment: continues an incremental load.
+ * @load_animation: loads an animation from a file.
+ * @save: saves a #GdkPixbuf to a file.
+ * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
+ * 
+ * A #GdkPixbufModule contains the necessary functions to load and save 
+ * images in a certain file format. 
+ * 
+ * A #GdkPixbufModule can be loaded dynamically from a #GModule.
+ * Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function 
+ * named <function>fill_vtable</function>, which will get called when the module
+ * is loaded and must set the function pointers of the #GdkPixbufModule. 
+ */
 typedef struct _GdkPixbufModule GdkPixbufModule;
 struct _GdkPixbufModule {
 	char *module_name;
@@ -141,7 +258,27 @@ struct _GdkPixbufModule {
 
 };
 
+/**
+ * GdkPixbufModuleFillVtableFunc:
+ * @module: a #GdkPixbufModule.
+ * 
+ * Defines the type of the function used to set the vtable of a 
+ * #GdkPixbufModule when it is loaded. 
+ * 
+ * Since: 2.2
+ */
+
 typedef void (* GdkPixbufModuleFillVtableFunc) (GdkPixbufModule *module);
+
+/**
+ * GdkPixbufModuleFillInfoFunc:
+ * @info: a #GdkPixbufFormat.
+ * 
+ * Defines the type of the function used to fill a 
+ * #GdkPixbufFormat structure with information about a module.
+ * 
+ * Since: 2.2
+ */
 typedef void (* GdkPixbufModuleFillInfoFunc) (GdkPixbufFormat *info);
 
 /*  key/value pairs that can be attached by the pixbuf loader  */
@@ -150,6 +287,19 @@ gboolean gdk_pixbuf_set_option  (GdkPixbuf   *pixbuf,
                                  const gchar *key,
                                  const gchar *value);
 
+/**
+ * GdkPixbufFormatFlags:
+ * @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
+ * @GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
+ * @GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. If this flag is not
+ *  set, &gdk-pixbuf; will use a lock to prevent multiple threads from using
+ *  this module at the same time. (Since 2.6)
+ * 
+ * Flags which allow a module to specify further details about the supported
+ * operations.
+ * 
+ * Since: 2.2
+ */
 typedef enum /*< skip >*/
 {
   GDK_PIXBUF_FORMAT_WRITABLE = 1 << 0,
@@ -157,6 +307,26 @@ typedef enum /*< skip >*/
   GDK_PIXBUF_FORMAT_THREADSAFE = 1 << 2
 } GdkPixbufFormatFlags;
 
+/**
+ * GdkPixbufFormat:
+ * @name: the name of the image format.
+ * @signature: the signature of the module.
+ * @domain: the message domain for the @description.
+ * @description: a description of the image format.
+ * @mime_types: a %NULL-terminated array of MIME types for the image format.
+ * @extensions: a %NULL-terminated array of typical filename extensions for the
+ *  image format.
+ * @flags: a combination of #GdkPixbufFormatFlags.
+ * @disabled: a boolean determining whether the loader is disabled.
+ * @license: a string containing license information, typically set to 
+ *  shorthands like "GPL", "LGPL", etc.
+ * 
+ * A #GdkPixbufFormat contains information about the image format accepted by a
+ * module. Only modules should access the fields directly, applications should
+ * use the <function>gdk_pixbuf_format_*</function> functions.
+ * 
+ * Since: 2.2
+ */
 struct _GdkPixbufFormat {
   gchar *name;
   GdkPixbufModulePattern *signature;
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 97d73b1..187a665 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -33,6 +33,69 @@
 #include "gdk-pixbuf-loader.h"
 #include "gdk-pixbuf-marshal.h"
 
+/**
+ * SECTION:gdk-pixbuf-loader
+ * @Short_description: Application-driven progressive image loading.
+ * @Title: GdkPixbufLoader
+ * @See_also: gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file()
+ * 
+ * #GdkPixbufLoader provides a way for applications to drive the
+ * process of loading an image, by letting them send the image data
+ * directly to the loader instead of having the loader read the data
+ * from a file.  Applications can use this functionality instead of
+ * gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() 
+ * when they need to parse image data in
+ * small chunks.  For example, it should be used when reading an
+ * image from a (potentially) slow network connection, or when
+ * loading an extremely large file.
+ * 
+ * 
+ * To use #GdkPixbufLoader to load an image, just create a new one,
+ * and call gdk_pixbuf_loader_write() to send the data to it.  When
+ * done, gdk_pixbuf_loader_close() should be called to end the stream
+ * and finalize everything.  The loader will emit three important
+ * signals throughout the process.  The first, "<link
+ * linkend="GdkPixbufLoader-size-prepared">size_prepared</link>",
+ * will be called as soon as the image has enough information to
+ * determine the size of the image to be used. If you want to scale
+ * the image while loading it, you can call gdk_pixbuf_loader_set_size()
+ * in response to this signal.
+ * 
+ * 
+ * The second signal, "<link
+ * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
+ * will be called as soon as the pixbuf of the desired has been 
+ * allocated.  You can obtain it by calling gdk_pixbuf_loader_get_pixbuf(). 
+ * If you want to use it, simply ref it.  
+ * In addition, no actual information will be passed in yet, so the
+ * pixbuf can be safely filled with any temporary graphics (or an
+ * initial color) as needed.  You can also call
+ * gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf.
+ * 
+ * 
+ * The last signal, "<link
+ * linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
+ * called every time a region is updated.  This way you can update a
+ * partially completed image.  Note that you do not know anything
+ * about the completeness of an image from the area updated.  For
+ * example, in an interlaced image, you need to make several passes
+ * before the image is done loading.
+ * 
+ * 
+ * <refsect2>
+ * <title>Loading an animation</title>
+ * <para>
+ * Loading an animation is almost as easy as loading an
+ * image. Once the first "<link
+ * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" signal
+ * has been emitted, you can call gdk_pixbuf_loader_get_animation()
+ * to get the #GdkPixbufAnimation struct and gdk_pixbuf_animation_get_iter()
+ * to get an #GdkPixbufAnimationIter for displaying it. 
+ * </para>
+ * </refsect2>
+ */
+
+
 enum {
         SIZE_PREPARED,
         AREA_PREPARED,
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.h b/gdk-pixbuf/gdk-pixbuf-loader.h
index 5d1f17c..f9743ee 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.h
+++ b/gdk-pixbuf/gdk-pixbuf-loader.h
@@ -45,7 +45,12 @@ G_BEGIN_DECLS
 #define GDK_IS_PIXBUF_LOADER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GDK_TYPE_PIXBUF_LOADER))
 #define GDK_PIXBUF_LOADER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GDK_TYPE_PIXBUF_LOADER, GdkPixbufLoaderClass))
 
-
+/**
+ * GdkPixbufLoader:
+ * 
+ * The <structname>GdkPixbufLoader</structname> struct contains only private
+ * fields. 
+ */
 typedef struct _GdkPixbufLoader GdkPixbufLoader;
 struct _GdkPixbufLoader
 {
diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c
index bf08018..6dbe18b 100644
--- a/gdk-pixbuf/gdk-pixbuf-scale.c
+++ b/gdk-pixbuf/gdk-pixbuf-scale.c
@@ -27,6 +27,78 @@
 #include "gdk-pixbuf-private.h"
 #include "pixops/pixops.h"
 
+/**
+ * SECTION:scaling
+ * @Short_description: Scaling pixbufs and scaling and compositing pixbufs
+ * @Title: Scaling
+ * @See_also:    <link linkend="gdk-GdkRGB">GdkRGB</link>.
+ * 
+ * The &gdk-pixbuf; contains functions to scale pixbufs, to scale
+ * pixbufs and composite against an existing image, and to scale
+ * pixbufs and composite against a solid color or checkerboard.
+ * Compositing a checkerboard is a common way to show an image with
+ * an alpha channel in image-viewing and editing software.
+ * 
+ * 
+ * Since the full-featured functions (gdk_pixbuf_scale(),
+ * gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
+ * rather complex to use and have many arguments, two simple
+ * convenience functions are provided, gdk_pixbuf_scale_simple() and
+ * gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
+ * given size, scale an original image to fit, and then return the
+ * new pixbuf.
+ * 
+ * 
+ * Scaling and compositing functions take advantage of MMX hardware
+ * acceleration on systems where MMX is supported.  If gdk-pixbuf is built
+ * with the Sun mediaLib library, these functions are instead accelerated
+ * using mediaLib, which provides hardware acceleration on Intel, AMD,
+ * and Sparc chipsets.  If desired, mediaLib support can be turned off by
+ * setting the GDK_DISABLE_MEDIALIB environment variable.  
+ * 
+ * 
+ * The following example demonstrates handling an expose event by
+ * rendering the appropriate area of a source image (which is scaled
+ * to fit the widget) onto the widget's window.  The source image is
+ * rendered against a checkerboard, which provides a visual
+ * representation of the alpha channel if the image has one. If the
+ * image doesn't have an alpha channel, calling
+ * gdk_pixbuf_composite_color() function has exactly the same effect
+ * as calling gdk_pixbuf_scale().
+ * 
+ * 
+ * <example>
+ * <title>Handling an expose event.</title>
+ * <para>
+ * <programlisting>
+ * gboolean
+ * expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
+ * {
+ *   GdkPixbuf *dest;
+ * 
+ *   dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);
+ * 
+ *   gdk_pixbuf_composite_color (pixbuf, dest,
+ *                               0, 0, event->area.width, event->area.height,
+ *                               -event->area.x, -event->area.y,
+ *                               (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
+ *                               (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
+ *                               GDK_INTERP_BILINEAR, 255,
+ *                               event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
+ * 
+ *   gdk_draw_pixbuf (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], dest,
+ *                    0, 0, event->area.x, event->area.y,
+ *                    event->area.width, event->area.height,
+ *                    GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);
+ *   
+ *   gdk_pixbuf_unref (dest);
+ *   
+ *   return TRUE;
+ * }
+ * </programlisting>
+ * </para>
+ * </example>
+ */
 
 
 /**
diff --git a/gdk-pixbuf/gdk-pixbuf-simple-anim.h b/gdk-pixbuf/gdk-pixbuf-simple-anim.h
index cb96c53..496688f 100644
--- a/gdk-pixbuf/gdk-pixbuf-simple-anim.h
+++ b/gdk-pixbuf/gdk-pixbuf-simple-anim.h
@@ -32,6 +32,11 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GdkPixbufSimpleAnim:
+ * 
+ * An opaque struct representing a simple animation.
+ */
 typedef struct _GdkPixbufSimpleAnim GdkPixbufSimpleAnim;
 typedef struct _GdkPixbufSimpleAnimClass GdkPixbufSimpleAnimClass;
 
diff --git a/gdk-pixbuf/gdk-pixbuf-transform.h b/gdk-pixbuf/gdk-pixbuf-transform.h
index 4965acf..d4757ff 100644
--- a/gdk-pixbuf/gdk-pixbuf-transform.h
+++ b/gdk-pixbuf/gdk-pixbuf-transform.h
@@ -38,7 +38,38 @@ G_BEGIN_DECLS
 
 /* Scaling */
 
-/* Interpolation modes */
+/**
+ * GdkInterpType:
+ * @GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest
+ *  and lowest quality mode. Quality is normally unacceptable when scaling 
+ *  down, but may be OK when scaling up.
+ * @GDK_INTERP_TILES: This is an accurate simulation of the PostScript
+ *  image operator without any interpolation enabled.  Each pixel is
+ *  rendered as a tiny parallelogram of solid color, the edges of which
+ *  are implemented with antialiasing.  It resembles nearest neighbor for
+ *  enlargement, and bilinear for reduction.
+ * @GDK_INTERP_BILINEAR: Best quality/speed balance; use this mode by
+ *  default. Bilinear interpolation.  For enlargement, it is
+ *  equivalent to point-sampling the ideal bilinear-interpolated image.
+ *  For reduction, it is equivalent to laying down small tiles and
+ *  integrating over the coverage area.
+ * @GDK_INTERP_HYPER: This is the slowest and highest quality
+ *  reconstruction function. It is derived from the hyperbolic filters in
+ *  Wolberg's "Digital Image Warping", and is formally defined as the
+ *  hyperbolic-filter sampling the ideal hyperbolic-filter interpolated
+ *  image (the filter is designed to be idempotent for 1:1 pixel mapping).
+ * 
+ *  This enumeration describes the different interpolation modes that
+ *  can be used with the scaling functions. @GDK_INTERP_NEAREST is 
+ *  the fastest scaling method, but has horrible quality when 
+ *  scaling down. @GDK_INTERP_BILINEAR is the best choice if you 
+ *  aren't sure what to choose, it has a good speed/quality balance.
+ * 
+ *  <note>
+ * 	Cubic filtering is missing from the list; hyperbolic
+ * 	interpolation is just as fast and results in higher quality.
+ *  </note>
+ */
 typedef enum {
 	GDK_INTERP_NEAREST,
 	GDK_INTERP_TILES,
@@ -46,6 +77,16 @@ typedef enum {
 	GDK_INTERP_HYPER
 } GdkInterpType;
 
+/**
+ * GdkPixbufRotation:
+ * @GDK_PIXBUF_ROTATE_NONE: No rotation.
+ * @GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE: Rotate by 90 degrees.
+ * @GDK_PIXBUF_ROTATE_UPSIDEDOWN: Rotate by 180 degrees.
+ * @GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees.
+ * 
+ * The possible rotations which can be passed to gdk_pixbuf_rotate_simple().
+ * To make them easier to use, their numerical values are the actual degrees.
+ */
 typedef enum {
 	GDK_PIXBUF_ROTATE_NONE             =   0,
 	GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE =  90,
diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c
index 08d09c6..f2e889b 100644
--- a/gdk-pixbuf/gdk-pixbuf-util.c
+++ b/gdk-pixbuf/gdk-pixbuf-util.c
@@ -28,6 +28,17 @@
 #include "gdk-pixbuf-transform.h"
 #include "gdk-pixbuf-private.h"
 
+/**
+ * SECTION:util
+ * @Short_description: Utility and miscellaneous convenience functions.
+ * @Title: Utilities
+ * @See_also: #GdkPixbuf
+ * 
+ * These functions provide miscellaneous utilities for manipulating
+ * pixbufs.  The pixel data in pixbufs may of course be manipulated
+ * directly by applications, but several common operations can be
+ * performed by these functions instead.
+ */
 
 
 /**
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index 6b59b85..8faa6f5 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -39,6 +39,77 @@
 #include <gio/gio.h>
 #include "gdk-pixbuf-marshal.c"
 
+/**
+ * SECTION:creating
+ * @Short_description: Creating a pixbuf from image data that is already in memory.
+ * @Title: Image Data in Memory
+ * @See_also: gdk_pixbuf_finalize().
+ * 
+ * The most basic way to create a pixbuf is to wrap an existing pixel
+ * buffer with a #GdkPixbuf structure.  You can use the
+ * gdk_pixbuf_new_from_data() function to do this You need to specify
+ * the destroy notification function that will be called when the
+ * data buffer needs to be freed; this will happen when a #GdkPixbuf
+ * is finalized by the reference counting functions If you have a
+ * chunk of static data compiled into your application, you can pass
+ * in %NULL as the destroy notification function so that the data
+ * will not be freed.
+ * 
+ * 
+ * The gdk_pixbuf_new() function can be used as a convenience to
+ * create a pixbuf with an empty buffer.  This is equivalent to
+ * allocating a data buffer using <function>malloc()</function> and 
+ * then wrapping it with gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() 
+ * function will compute an optimal rowstride so that rendering can be 
+ * performed with an efficient algorithm.
+ * 
+ * 
+ * As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+ * function to create a pixbuf from inline XPM image data.
+ * 
+ * 
+ * You can also copy an existing pixbuf with the gdk_pixbuf_copy()
+ * function.  This is not the same as just doing a g_object_ref()
+ * on the old pixbuf; the copy function will actually duplicate the
+ * pixel data in memory and create a new #GdkPixbuf structure for it.
+ */
+
+/**
+ * SECTION:refcounting
+ * @Short_description: Functions for reference counting and memory management on pixbufs.
+ * @Title: Reference Counting and Memory Mangement
+ * @See_also: #GdkPixbuf, gdk_pixbuf_new_from_data().
+ * 
+ * #GdkPixbuf structures are reference counted.  This means that an
+ * application can share a single pixbuf among many parts of the
+ * code.  When a piece of the program needs to keep a pointer to a
+ * pixbuf, it should add a reference to it by calling g_object_ref().
+ * When it no longer needs the pixbuf, it should subtract a reference
+ * by calling g_object_unref().  The pixbuf will be destroyed when
+ * its reference count drops to zero.  Newly-created #GdkPixbuf
+ * structures start with a reference count of one.
+ * 
+ * 
+ * <note>
+ * As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and
+ * gdk_pixbuf_unref() are deprecated in favour of g_object_ref()
+ * and g_object_unref () resp.
+ * </note>
+ * 
+ * <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
+ * data and to free the #GdkPixbuf structure itself.  Most of the
+ * library functions that create #GdkPixbuf structures create the
+ * pixel data by themselves and define the way it should be freed;
+ * you do not need to worry about those.  The only function that lets
+ * you specify how to free the pixel data is
+ * gdk_pixbuf_new_from_data().  Since you pass it a pre-allocated
+ * pixel buffer, you must also specify a way to free that data.  This
+ * is done with a function of type #GdkPixbufDestroyNotify.  When a
+ * pixbuf created with gdk_pixbuf_new_from_data() is finalized, your
+ * destroy notification function will be called, and it is its
+ * responsibility to free the pixel array.
+ */
+
 static void gdk_pixbuf_finalize     (GObject        *object);
 static void gdk_pixbuf_set_property (GObject        *object,
 				     guint           prop_id,
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index 2147950..162c71e 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -22,6 +22,19 @@
 #include "gdk-pixdata.h"
 #include <string.h>
 
+/**
+ * SECTION:inline
+ * @Short_description: Functions for inlined pixbuf handling.
+ * @Title: Inline data
+ * 
+ * Using #GdkPixdata, images can be compiled into an application,
+ * making it unnecessary to refer to external image files at runtime.
+ * &gdk-pixbuf; includes a utility named gdk-pixbuf-csource, which 
+ * can be used to convert image files into #GdkPixdata structures suitable
+ * for inclusion in C sources. To convert the #GdkPixdata structures back 
+ * into #GdkPixbuf<!-- -->s, use gdk_pixbuf_from_pixdata.
+ */
+
 #define APPEND g_string_append_printf
 
 /* --- functions --- */