[gdk-pixbuf/ebassi/gi-docgen: 5/16] docs: Port to the gi-docgen syntax and style

[Emmanuele Bassi <ebassi src gnome org>]

commit 0ad5532347210a53490734b9b1dda31f73560a4d
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sat Mar 20 22:52:01 2021 +0000

    docs: Port to the gi-docgen syntax and style
    
    Drop the gtk-doc SECTION markers, and move documentation to classes or
    separate documents.

 docs/gdk-pixbuf.toml.in             |   3 +
 docs/meson.build                    |   1 +
 docs/scaling-compositing.md         |  44 +++++++
 gdk-pixbuf/gdk-pixbuf-animation.c   |  27 +++--
 gdk-pixbuf/gdk-pixbuf-animation.h   |  11 --
 gdk-pixbuf/gdk-pixbuf-core.h        |  80 +++++++------
 gdk-pixbuf/gdk-pixbuf-features.h.in |  20 +---
 gdk-pixbuf/gdk-pixbuf-io.c          | 109 ++++++++---------
 gdk-pixbuf/gdk-pixbuf-io.h          |  76 +++++-------
 gdk-pixbuf/gdk-pixbuf-loader.c      |  83 ++++++-------
 gdk-pixbuf/gdk-pixbuf-loader.h      |   8 +-
 gdk-pixbuf/gdk-pixbuf-scale.c       |  43 -------
 gdk-pixbuf/gdk-pixbuf-transform.h   |  14 ++-
 gdk-pixbuf/gdk-pixbuf-util.c        |  13 --
 gdk-pixbuf/gdk-pixbuf.c             | 230 +++++++++++++++++++-----------------
 15 files changed, 363 insertions(+), 399 deletions(-)
---
diff --git a/docs/gdk-pixbuf.toml.in b/docs/gdk-pixbuf.toml.in
index 50299e5fd..bd5cfe935 100644
--- a/docs/gdk-pixbuf.toml.in
+++ b/docs/gdk-pixbuf.toml.in
@@ -40,6 +40,9 @@ content_images = [
   'composite.png',
   'gnome-gmush-1.png',
 ]
+content_files = [
+  'scaling-compositing.md',
+]
 
 [[object]]
 name = "PIXBUF_DEPRECATED_IN_2_0_FOR"
diff --git a/docs/meson.build b/docs/meson.build
index d40ba61c0..d4c5fe5ea 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -14,6 +14,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
 docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference'
 
 expand_content_md_files = [
+  'scaling-compositing.md',
 ]
 
 build_docs = get_option('gtk_doc')
diff --git a/docs/scaling-compositing.md b/docs/scaling-compositing.md
new file mode 100644
index 000000000..3abc75e73
--- /dev/null
+++ b/docs/scaling-compositing.md
@@ -0,0 +1,44 @@
+Title: Scaling and compositing
+
+----
+
+The `GdkPixBuf` class contains methods to scale pixbufs, to scale
+pixbufs and alpha blend against an existing image, and to scale
+pixbufs and alpha blend against a solid color or checkerboard.
+Alpha blending a checkerboard is a common way to show an image with
+an alpha channel in image-viewing and editing software.
+
+Note that in these functions, the terms ‘alpha blending’ and ‘compositing’
+are used synonymously.
+
+Since the full-featured functions [method@GdkPixbuf.Pixbuf.scale],
+[method@GdkPixbuf.Pixbuf.composite], and [`method@GdkPixbuf.Pixbuf.composite_color`]
+are rather complex to use and have many arguments, two simple
+convenience functions are provided, [`method@GdkPixbuf.Pixbuf.scale_simple`]
+and [`method@GdkPixbuf.Pixbuf.composite_color_simple`] which create a new
+pixbuf of a given size, scale an original image to fit, and then return it.
+
+If the destination pixbuf was created from a read only source, these
+operations will force a copy into a mutable buffer.
+
+Scaling and alpha blending functions take advantage of MMX hardware
+acceleration on systems where MMX is supported. If `GdkPixbuf` 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 alpha blending function used is:
+
+```
+Cd = Cs·As + Cd(1-As)
+```
+
+where `Cd` is the destination pixel color, `Cs` is the source pixel color,
+and `As` is the source pixel alpha.
+
+**NOTE**: It is recommended to use [Cairo][cairo] for scaling and
+compositing, by using the contents of a `GdkPixbuf` pixel buffer as the
+data for a Cairo image surface.
+
+[cairo]: https://www.cairographics.org
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c
index c8f2695e3..9b7372e00 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.c
+++ b/gdk-pixbuf/gdk-pixbuf-animation.c
@@ -30,21 +30,30 @@
 #include <glib/gstdio.h>
 
 /**
- * SECTION:animation
- * @Short_description: Animated images.
- * @Title: Animations
- * @See_also: #GdkPixbufLoader.
+ * GdkPixbufAnimation:
+ *
+ * An opaque object representing an animation.
  *
  * The GdkPixBuf library provides a simple mechanism to load and
  * represent animations. An animation is conceptually a series of
- * frames to be displayed over time. 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 GdkPixBuf what should
+ * frames to be displayed over time.
+ *
+ * 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 `GdkPixbuf` what should
  * be displayed at a given point in time.
  */
 
+/**
+ * GdkPixbufAnimationIter:
+ *
+ * An opaque object representing an iterator which points to a
+ * certain position in an animation.
+ */
+
 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 ad0c39c3b..cae551edd 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.h
+++ b/gdk-pixbuf/gdk-pixbuf-animation.h
@@ -36,20 +36,9 @@ 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 ())
diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h
index e03357d71..4b8c9b9b2 100644
--- a/gdk-pixbuf/gdk-pixbuf-core.h
+++ b/gdk-pixbuf/gdk-pixbuf-core.h
@@ -44,17 +44,23 @@ G_BEGIN_DECLS
  *  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_xlib_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.
  *
- * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode
+ * Control the alpha channel for drawables.
+ *
+ * These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha()
+ * in gdk-pixbuf-xlib 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.
+ *
+ * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode in GdkPixbuf,
+ *   and the Xlib utility functions have been split out to their own
+ *   library, gdk-pixbuf-xlib
  */
 typedef enum
 {
@@ -67,7 +73,9 @@ typedef enum
  * @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.
+ * 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
@@ -78,15 +86,6 @@ typedef enum {
 
 /* 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 ())
@@ -101,20 +100,23 @@ typedef struct _GdkPixbuf GdkPixbuf;
  * @data: (closure): 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.
+ * 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 type `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.
+ * Error domain used for pixbuf operations.
+ *
+ * Indicates that the error code will be in the `GdkPixbufError` enumeration.
+ *
+ * See the `GError` for information on error domains and error codes.
  */
 #define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
 
@@ -129,9 +131,10 @@ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
  * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
  * @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded.
  * 
- * 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.
+ * 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 */
@@ -347,15 +350,18 @@ gboolean gdk_pixbuf_savev_utf8     (GdkPixbuf  *pixbuf,
  * @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()
+ * Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback].
+ *
+ * This function 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.
+ *
+ * Returns: `TRUE` if successful, `FALSE` otherwise
  * 
  * Since: 2.4
- * Returns: %TRUE if successful, %FALSE (with @error set) if failed.
  */
 
 typedef gboolean (*GdkPixbufSaveFunc)   (const gchar *buf,
diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in
index 7efdc0e39..600d03220 100644
--- a/gdk-pixbuf/gdk-pixbuf-features.h.in
+++ b/gdk-pixbuf/gdk-pixbuf-features.h.in
@@ -7,15 +7,6 @@
 
 #include <glib.h>
 
-/**
- * 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:
  * 
@@ -37,9 +28,10 @@
 /**
  * GDK_PIXBUF_VERSION:
  * 
- * Contains the full version of the gdk-pixbuf header as a string.
+ * Contains the full version of GdkPixbuf as a string.
+ *
  * This is the version being compiled against; contrast with
- * #gdk_pixbuf_version.
+ * `gdk_pixbuf_version`.
  */
 
 #define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@)
@@ -81,7 +73,7 @@
  * 
  * 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_MAJOR` macro, which represents the major version of the
  * gdk-pixbuf headers you have included.
  */
 /**
@@ -93,7 +85,7 @@
  * 
  * 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_MINOR` macro, which represents the minor version of the
  * gdk-pixbuf headers you have included.
  */
 /**
@@ -105,7 +97,7 @@
  * 
  * 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_MICRO` macro, which represents the micro version of the
  * gdk-pixbuf headers you have included.
  */
 /**
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 2dc2ea6da..13bf5af16 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -48,80 +48,69 @@
 #endif
 
 /**
- * SECTION:file-loading
- * @Short_description: Loading a pixbuf from a file.
- * @Title: File Loading
- * @See_also: #GdkPixbufLoader.
+ * 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.
+ * @is_save_option_supported: returns whether a save option key is supported by the module
  * 
- * The GdkPixBuf 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.
+ * A `GdkPixbufModule` contains the necessary functions to load and save
+ * images in a certain file format.
  * 
+ * If `GdkPixbuf` has been compiled with `GModule` support, it can be extended
+ * by modules which can load (and perhaps also save) new image and animation
+ * formats.
+ *
+ * ## Implementing modules
  * 
- * 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. GdkPixBuf 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 GdkPixBuf
- * @Title: Module Interface
- * 
- * If GdkPixBuf 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 `fill_info` and
- * a #GdkPixbufModuleFillVtableFunc function named
- * `fill_vtable`.
+ * The `GdkPixbuf` interfaces needed for implementing modules are contained in
+ * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
+ * animations). They are not covered by the same stability guarantees as the
+ * regular GdkPixbuf API. To underline this fact, they are protected by the
+ * `GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol.
+ *
+ * Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function
+ * named `fill_vtable`, which will get called when the module
+ * is loaded and must set the function pointers of the `GdkPixbufModule`.
  * 
  * 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 `fill_info` function. An
- * external utility, gdk-pixbuf-query-loaders, uses this to create a text
+ * (which may require calling `dlopen` to load image libraries), modules export
+ * their signatures (and other information) via the `fill_info` function. An
+ * external utility, `gdk-pixbuf-query-loaders`, 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 GdkPixBuf to obtain the list of
+ * This file is then read at runtime by `GdkPixbuf` 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
+ * `GdkPixbufModule`. If a particular functionality is not implemented, the
  * `fill_vtable` 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 GdkPixBuf can
- * supply a generic #load implementation wrapping the incremental loading. 
+ * 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 `GdkPixbuf`
+ * can supply a generic `load` implementation wrapping the incremental loading.
+ *
+ * ## Installing modules
  * 
  * Installing a module is a two-step process:
- * - copy the module file(s) to the loader directory (normally
- *   `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
- *   environment variable `GDK_PIXBUF_MODULEDIR`) 
- * - call gdk-pixbuf-query-loaders to update the module file (normally
- *   `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the
- *   environment variable `GDK_PIXBUF_MODULE_FILE`)
- * 
- * The GdkPixBuf interfaces needed for implementing modules are contained in
- * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
- * animations). They are not covered by the same stability guarantees as the
- * regular  GdkPixBuf API. To underline this fact, they are protected by
- * `#ifdef GDK_PIXBUF_ENABLE_BACKEND`.
+ *
+ *  - copy the module file(s) to the loader directory (normally
+ *    `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
+ *    environment variable `GDK_PIXBUF_MODULEDIR`)
+ *  - call `gdk-pixbuf-query-loaders` to update the module file (normally
+ *    `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden
+ *    by the environment variable `GDK_PIXBUF_MODULE_FILE`)
  */
 
-
 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 89b0830e1..f8270f52c 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.h
+++ b/gdk-pixbuf/gdk-pixbuf-io.h
@@ -173,34 +173,37 @@ typedef void (* GdkPixbufModuleUpdatedFunc)  (GdkPixbuf *pixbuf,
  * @mask: mask containing bytes which modify how the prefix is matched against
  *  test data
  * @relevance: relevance of this pattern
+ *
+ * The signature prefix for a module.
  * 
  * 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 
+ * 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. 
+ * not matched, "don't-care"-bytes, zeros and non-zeros, respectively.
+ *
  * 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'. 
+ * like an 'x'.
  * 
  * The signature of a module is stored as an array of 
- * #GdkPixbufModulePatterns. The array is terminated by a pattern
- * where the @prefix is %NULL.
- * 
+ * `GdkPixbufModulePatterns`. The array is terminated by a pattern
+ * where the `prefix` is `NULL`.
  * 
- * <informalexample><programlisting>
+ * ```c
  * 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>
+ * ```
+ *
+ * In the example above, the signature matches e.g. "auud\0" with
+ * relevance 100, and "blau" with relevance 90.
  * 
  * Since: 2.2
  */
@@ -211,31 +214,6 @@ 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.
- * @is_save_option_supported: returns whether a save option key is supported by the module
- * 
- * 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;
@@ -332,21 +310,23 @@ typedef enum /*< skip >*/
 
 /**
  * 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.
+ * @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: (array zero-terminated=1): the MIME types for the image format
+ * @extensions: (array zero-terminated=1): 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.
+ *   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.
+ * A `GdkPixbufFormat` contains information about the image format accepted
+ * by a module.
+ *
+ * Only modules should access the fields directly, applications should
+ * use the `gdk_pixbuf_format_*` family of functions.
  * 
  * Since: 2.2
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 81c5afb75..5ef462d0d 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -32,52 +32,53 @@
 #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:
+ *
+ * Incremental image loader.
  * 
- * #GdkPixbufLoader provides a way for applications to drive the
+ * `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, #GdkPixbufLoader::size-prepared,
- * will be emitted 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, #GdkPixbufLoader::area-prepared, will be emitted 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. You can also call gdk_pixbuf_loader_get_pixbuf() later and get
- * the same pixbuf.
- * 
- * The last signal, #GdkPixbufLoader::area-updated, gets emitted 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 updated area. For example, in an interlaced image, you need to
- * make several passes before the image is done loading.
+ * 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, create a new instance,
+ * and call [method@GdkPixbuf.PixbufLoader.write] to send the data
+ * to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be
+ * called to end the stream and finalize everything.
+ *
+ * The loader will emit three important signals throughout the process:
+ *
+ *  - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted 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 [method@GdkPixbuf.PixbufLoader.set_size] in
+ *    response to this signal.
+ *  - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as
+ *    soon as the pixbuf of the desired has been allocated. You can obtain
+ *    the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf].
+ *    If you want to use it, simply acquire a reference to it. You can
+ *    also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
+ *    pixbuf.
+ *  - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted 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 updated area. For example, in an
+ *    interlaced image you will need to make several passes before the
+ *    image is done loading.
  * 
- * # Loading an animation 
+ * ## Loading an animation
  *
- * Loading an animation is almost as easy as loading an image. Once the first
- * #GdkPixbufLoader::area-prepared 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 a #GdkPixbufAnimationIter for
- * displaying it. 
+ * Loading an animation is almost as easy as loading an image. Once the
+ * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+ * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to
+ * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call
+ * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a
+ * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the
+ * desired time stamp.
  */
 
 
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.h b/gdk-pixbuf/gdk-pixbuf-loader.h
index 83648205f..1cc34136b 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.h
+++ b/gdk-pixbuf/gdk-pixbuf-loader.h
@@ -43,18 +43,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 GdkPixbufLoader struct contains only private
- * fields. 
- */
 typedef struct _GdkPixbufLoader GdkPixbufLoader;
 struct _GdkPixbufLoader
 {
+  /*< private >*/
   GObject parent_instance;
   
-  /*< private >*/
   gpointer priv;
 };
 
diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c
index 84e8e10c3..863de8b83 100644
--- a/gdk-pixbuf/gdk-pixbuf-scale.c
+++ b/gdk-pixbuf/gdk-pixbuf-scale.c
@@ -25,49 +25,6 @@
 #include "gdk-pixbuf-private.h"
 #include "pixops/pixops.h"
 
-/**
- * SECTION:scaling
- * @Short_description: Scaling pixbufs and scaling and alpha blending pixbufs
- * @Title: Scaling
- * 
- * The GdkPixBuf contains functions to scale pixbufs, to scale
- * pixbufs and alpha blend against an existing image, and to scale
- * pixbufs and alpha blend against a solid color or checkerboard.
- * Alpha blending a checkerboard is a common way to show an image with
- * an alpha channel in image-viewing and editing software.
- * 
- * Note that in these functions, the terms ‘alpha blending’ and ‘compositing’
- * are used synonymously.
- * 
- * 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.
- * 
- * If the destination pixbuf was created from a readonly source, these
- * operations will force a copy into a mutable buffer.
- * 
- * Scaling and alpha blending 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 alpha blending function used is:
- *
- * |[<!-- language="plain" -->
- * Cd = Cs·As + Cd(1-As)
- * ]|
- *
- * where `Cd` is the destination pixel color, `Cs` is the source pixel color,
- * and `As` is the source pixel alpha.
- */
-
-
 /**
  * gdk_pixbuf_scale:
  * @src: a #GdkPixbuf
diff --git a/gdk-pixbuf/gdk-pixbuf-transform.h b/gdk-pixbuf/gdk-pixbuf-transform.h
index 24e5ad5ae..2ba28c49f 100644
--- a/gdk-pixbuf/gdk-pixbuf-transform.h
+++ b/gdk-pixbuf/gdk-pixbuf-transform.h
@@ -59,12 +59,13 @@ G_BEGIN_DECLS
  *  **Deprecated**: this interpolation filter is deprecated, as in reality
  *  it has a lower quality than the @GDK_INTERP_BILINEAR filter
  *  (Since: 2.38)
- * 
- * 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.
+ *
+ * Interpolation modes for scaling functions.
+ *
+ * The `GDK_INTERP_NEAREST` mode 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.
@@ -84,6 +85,7 @@ typedef enum {
  * @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 {
diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c
index db1562b76..89d5a9792 100644
--- a/gdk-pixbuf/gdk-pixbuf-util.c
+++ b/gdk-pixbuf/gdk-pixbuf-util.c
@@ -26,19 +26,6 @@
 #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.
- */
-
-
 /**
  * gdk_pixbuf_add_alpha:
  * @pixbuf: A #GdkPixbuf.
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index 2594b99e9..383fe024b 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -21,152 +21,162 @@
  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "config.h"
-
-#include <math.h>
-#include <stdlib.h>
-#include <string.h>
-
-#define GDK_PIXBUF_C_COMPILATION
-#include "gdk-pixbuf-private.h"
-#include "gdk-pixbuf-features.h"
-#include "gdk-pixbuf-enum-types.h"
-
-/* Include the marshallers */
-#include <glib-object.h>
-#include <gio/gio.h>
-#include "gdk-pixbuf-marshal.h"
-
 /**
- * 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().
+ * GdkPixbuf:
+ *
+ * A pixel buffer.
+ *
+ * `GdkPixbuf` contains information about an 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).
+ *
+ * ## Creating new `GdkPixbuf`
  * 
  * 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.
+ * buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the
+ * [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this.
  * 
- * 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 malloc() 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.
+ * Every time you create a new `GdkPixbuf` instance for some data, you
+ * will 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.
  * 
- * As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+ * The [`ctor GdkPixbuf Pixbuf new`] constructor function can be used
+ * as a convenience to create a pixbuf with an empty buffer; this is
+ * equivalent to allocating a data buffer using `malloc()` 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 [`ctor@GdkPixbuf.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().
+ * You can also copy an existing pixbuf with the [method Pixbuf copy]
+ * function. This is not the same as just acquiring a reference to
+ * the old pixbuf instance: the copy function will actually duplicate
+ * the pixel data in memory and create a new [class@Pixbuf] instance
+ * for it.
+ *
+ * ## Reference counting
  * 
- * #GdkPixbuf structures are reference counted.  This means that an
+ * `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.
- * 
- * > 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.
- * 
- * Finalizing 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.
- *
- * To provide preallocated pixel data, use
- * gdk_pixbuf_new_from_bytes().  The gdk_pixbuf_new_from_data() API is
- * an older variant that predates the existence of #GBytes.
- */
-
-/**
- * SECTION:gdk-pixbuf
- * @Short_description: Information that describes an image.
- * @Title: The GdkPixbuf Structure
+ * code. When a piece of the program needs to use a pixbuf, it should
+ * acquire a reference to it by calling `g_object_ref()`; when it no
+ * longer needs the pixbuf, it should release the reference it acquired
+ * by calling `g_object_unref()`. The resources associated with a
+ * `GdkPixbuf` will be freed when its reference count drops to zero.
+ * Newly-created `GdkPixbuf` instances start with a reference count
+ * of one.
  *
- * The #GdkPixbuf structure contains
- * information that describes an image in memory.
+ * ## Image Data
  *
- * ## Image Data ## {#image-data}
+ * Image data in a pixbuf is stored in memory in an uncompressed,
+ * packed format. Rows in the image are stored top to bottom, and
+ * in each row pixels are stored from left to right.
  *
- * 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.
+ * There may be padding at the end of a row.
  *
- * ## put_pixel() Example ## {#put-pixel}
+ * The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`],
+ * indicates the number of bytes between rows.
  *
- * The following code illustrates a simple put_pixel()
+ * **NOTE**: If you are copying raw pixbuf data with `memcpy()` 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
+ * `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use
+ * [method GdkPixbuf Pixbuf copy] instead, or compute the width in bytes of the
+ * last row as:
+ *
+ * ```c
+ * last_row = width * ((n_channels * bits_per_sample + 7) / 8);
+ * ```
+ *
+ * The same rule applies when iterating over each row of a `GdkPixbuf` pixels
+ * array.
+ *
+ * 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.
+ * channel.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
- * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
+ * 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);
+ *   int n_channels = gdk_pixbuf_get_n_channels (pixbuf);
  *
+ *   // Ensure that the pixbuf is valid
  *   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);
+ *   int width = gdk_pixbuf_get_width (pixbuf);
+ *   int height = gdk_pixbuf_get_height (pixbuf);
  *
+ *   // Ensure that the coordinates are in a valid range
  *   g_assert (x >= 0 && x < width);
  *   g_assert (y >= 0 && y < height);
  *
- *   rowstride = gdk_pixbuf_get_rowstride (pixbuf);
- *   pixels = gdk_pixbuf_get_pixels (pixbuf);
+ *   int rowstride = gdk_pixbuf_get_rowstride (pixbuf);
  *
- *   p = pixels + y * rowstride + x * n_channels;
+ *   // The pixel buffer in the GdkPixbuf instance
+ *   guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);
+ *
+ *   // The pixel we wish to modify
+ *   guchar *p = pixels + y * rowstride + x * n_channels;
  *   p[0] = red;
  *   p[1] = green;
  *   p[2] = blue;
  *   p[3] = alpha;
  * }
- * ]|
- *
- * 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.
- *
- * 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 `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf.
- * Use gdk_pixbuf_copy() instead, or compute the width in bytes of the
- * last row as `width * ((n_channels * bits_per_sample + 7) / 8)`.
+ * ```
+ *
+ * ## Loading images
+ *
+ * The `GdkPixBuf` class provides a simple mechanism for loading
+ * an image from a file in synchronous and asynchronous fashion.
+ *
+ * For GUI applications, it is recommended to use the asynchronous
+ * stream API to avoid blocking the control flow of the application.
+ *
+ * Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`]
+ * API for progressive image loading.
+ *
+ * ## Saving images
+ *
+ * The `GdkPixbuf` class provides methods for saving image data in
+ * a number of file formats. The formatted data can be written to a
+ * file or to a memory buffer. `GdkPixbuf` 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.
  */
 
+#include "config.h"
+
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define GDK_PIXBUF_C_COMPILATION
+#include "gdk-pixbuf-private.h"
+#include "gdk-pixbuf-features.h"
+#include "gdk-pixbuf-enum-types.h"
+
+/* Include the marshallers */
+#include <glib-object.h>
+#include <gio/gio.h>
+#include "gdk-pixbuf-marshal.h"
+
 static void gdk_pixbuf_finalize     (GObject        *object);
 static void gdk_pixbuf_set_property (GObject        *object,
                                     guint           prop_id,