Populated.

1999-11-04  Federico Mena Quintero  <federico@redhat.com>

	* doc/tmpl/gdk-pixbuf.sgml: Populated.

	* doc/tmpl/refcounting.sgml: Populated.

	* doc/tmpl/file-loading.sgml: Populated.

	* src/gdk-pixbuf.c: Added documentation comments.

	* src/gdk-pixbuf-io.c (gdk_pixbuf_new_from_file): Added
	documentation comments.

11 files changed, 194 insertions, 71 deletions

diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml
index fa110239ab..f6c303566f 100644
--- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml
@@ -1,21 +1,19 @@
 <!-- ##### SECTION Title ##### -->
-creating
+Creating a Pixbuf from Data in Memory
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Creating a pixbuf from image data that is already in memory.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+  <para>
 
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
 <para>
 
@@ -62,4 +60,9 @@ creating
 @data: 
 @Returns: 
 
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
diff --git a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
index d26f875855..9fcf2ea5c8 100644
--- a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
@@ -1,20 +1,29 @@
 <!-- ##### SECTION Title ##### -->
-file-loading
+File Loading
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Loading a pixbuf from a file.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+  <para>
+    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.
+  </para>
+
+  <para>
+    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.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+  <para>
+    #GdkPixbufLoader
+  </para>
 
 <!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
 <para>
@@ -24,4 +33,9 @@ file-loading
 @filename: 
 @Returns: 
 
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml
index 4a2aa5478e..ecb5a5bad7 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml
@@ -9,13 +9,11 @@ gdk-pixbuf-io
 
 </para>
 
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### USER_FUNCTION ModulePreparedNotifyFunc ##### -->
 <para>
 
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
index 3dc9606b2f..56af53f7d8 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
@@ -9,13 +9,11 @@ GdkPixbufLoader
 
 </para>
 
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
 <para>
 
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
index 8f95817ea0..0276b40cb9 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
@@ -1,36 +1,41 @@
 <!-- ##### SECTION Title ##### -->
-gdk-pixbuf
+The GdkPixbuf Structure
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Information that describes an image.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
 
+  <para>
+    The <structname>GdkPixbuf</structname> structure contains
+    information that describes an image in memory.  It is actually a
+    simple wrapper that adds reference counting capabilities to an
+    #ArtPixBuf structure.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+  <para>
+    #ArtPixBuf
+  </para>
 
 <!-- ##### STRUCT GdkPixbuf ##### -->
-<para>
+  <para>
+    This is the main structure in the GdkPixbuf library.  This
+    structure adds reference counting capabilities to an #ArtPixBuf
+    structure.
+  </para>
 
-</para>
-
-@ref_count: 
-@art_pixbuf: 
+@ref_count: Reference count.
+@art_pixbuf: An #ArtPixBuf that actually contains the description of
+the image data.
 
 <!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
 <para>
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
@@ -38,8 +43,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
@@ -47,8 +52,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
@@ -56,8 +61,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
@@ -65,8 +70,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
@@ -74,8 +79,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
@@ -83,8 +88,8 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
+@pixbuf:
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
@@ -92,7 +97,12 @@ gdk-pixbuf
 
 </para>
 
-@pixbuf: 
-@Returns: 
-
+@pixbuf:
+@Returns:
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
diff --git a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
index a615cc27ba..595322a37f 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
@@ -9,13 +9,11 @@ GnomeCanvasPixbuf
 
 </para>
 
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
 <para>
 
diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
index ec2b62d0b8..63f1121aea 100644
--- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
@@ -1,25 +1,30 @@
 <!-- ##### SECTION Title ##### -->
-refcounting
+Reference Counting
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Functions to perform reference counting on a #GdkPixbuf.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+  <para>
+    #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.  When it no longer needs
+    the pixbuf, it should subtract a reference.  The pixbuf will be
+    destroyed when its reference count drops to zero.  Newly-created
+    #GdkPixbuf structures start with a reference count of one.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+  <para>
+    #GdkPixbuf
+    #ArtPixBuf
+  </para>
 
 <!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
-<para>
+  <para>
 
-</para>
+  </para>
 
 @pixbuf: 
 
@@ -32,3 +37,9 @@ refcounting
 @pixbuf: 
 
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
diff --git a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
index 0576a730b9..e70a79d892 100644
--- a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
@@ -9,13 +9,11 @@ rendering
 
 </para>
 
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### ENUM GdkPixbufAlphaMode ##### -->
 <para>
 
diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index d1bc556de3..e1d0c55814 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,5 +1,16 @@
 1999-11-04  Federico Mena Quintero  <federico@redhat.com>
 
+	* doc/tmpl/gdk-pixbuf.sgml: Populated.
+
+	* doc/tmpl/refcounting.sgml: Populated.
+
+	* doc/tmpl/file-loading.sgml: Populated.
+
+	* src/gdk-pixbuf.c: Added documentation comments.
+
+	* src/gdk-pixbuf-io.c (gdk_pixbuf_new_from_file): Added
+	documentation comments.
+
 	* doc/: Finished integrating the documentation framework.
 
 1999-11-03  Federico Mena Quintero  <federico@redhat.com>
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index e2b692f6d9..64ddd1b563 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -221,6 +221,18 @@ gdk_pixbuf_get_module (gchar *buffer, gint size)
 	return NULL;
 }
 
+/**
+ * gdk_pixbuf_new_from_file:
+ * @filename: Name of file to load.
+ * 
+ * Creates a new pixbuf by loading an image from a file.  The file format is
+ * detected automatically.
+ * 
+ * Return value: A newly-created pixbuf, or NULL if any of several error
+ * conditions occurred:  the file could not be opened, there was no loader for
+ * the file's format, there was not enough memory to allocate the image buffer,
+ * or the image file contained invalid data.
+ **/
 GdkPixbuf *
 gdk_pixbuf_new_from_file (const char *filename)
 {
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index cc0d841291..b1ff7f6537 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -107,6 +107,10 @@ free_buffer (gpointer user_data, gpointer data)
 	free (data);
 }
 
+
+
+/* Create an empty pixbuf */
+
 /**
  * gdk_pixbuf_new:
  * @format: Image format.
@@ -114,11 +118,11 @@ free_buffer (gpointer user_data, gpointer data)
  * @bits_per_sample: Number of bits per color sample.
  * @width: Width of image in pixels.
  * @height: Height of image in pixels.
- * 
+ *
  * Creates a new &GdkPixbuf structure and allocates a buffer for it.  The buffer
  * has an optimal rowstride.  Note that the buffer is not cleared; you will have
  * to fill it completely.
- * 
+ *
  * Return value: A newly-created &GdkPixbuf, or NULL if not enough memory
  * could be allocated for the image buffer.
  **/
@@ -148,8 +152,18 @@ gdk_pixbuf_new (ArtPixFormat format, gboolean has_alpha, int bits_per_sample,
 					 free_buffer, NULL);
 }
 
+
 
 /* Convenience functions */
+
+/**
+ * gdk_pixbuf_get_format:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the image format (color model) of a pixbuf.
+ *
+ * Return value: Image format.
+ **/
 ArtPixFormat
 gdk_pixbuf_get_format (GdkPixbuf *pixbuf)
 {
@@ -160,6 +174,14 @@ gdk_pixbuf_get_format (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->format);
 }
 
+/**
+ * gdk_pixbuf_get_n_channels:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the number of channels of a pixbuf.
+ *
+ * Return value: Number of channels.
+ **/
 int
 gdk_pixbuf_get_n_channels (GdkPixbuf *pixbuf)
 {
@@ -169,6 +191,14 @@ gdk_pixbuf_get_n_channels (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->n_channels);
 }
 
+/**
+ * gdk_pixbuf_get_has_alpha:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries whether a pixbuf has an alpha channel (opacity information).
+ *
+ * Return value: TRUE if it has an alpha channel, FALSE otherwise.
+ **/
 int
 gdk_pixbuf_get_has_alpha (GdkPixbuf *pixbuf)
 {
@@ -178,6 +208,14 @@ gdk_pixbuf_get_has_alpha (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->has_alpha);
 }
 
+/**
+ * gdk_pixbuf_get_bits_per_sample:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the number of bits per color sample in a pixbuf.
+ *
+ * Return value: Number of bits per color sample.
+ **/
 int
 gdk_pixbuf_get_bits_per_sample (GdkPixbuf *pixbuf)
 {
@@ -187,6 +225,14 @@ gdk_pixbuf_get_bits_per_sample (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->bits_per_sample);
 }
 
+/**
+ * gdk_pixbuf_get_pixels:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries a pointer to the pixel data of a pixbuf.
+ *
+ * Return value: A pointer to the pixbuf's pixel data.
+ **/
 guchar *
 gdk_pixbuf_get_pixels (GdkPixbuf *pixbuf)
 {
@@ -196,6 +242,14 @@ gdk_pixbuf_get_pixels (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->pixels);
 }
 
+/**
+ * gdk_pixbuf_get_width:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the width of a pixbuf.
+ *
+ * Return value: Width in pixels.
+ **/
 int
 gdk_pixbuf_get_width (GdkPixbuf *pixbuf)
 {
@@ -205,6 +259,14 @@ gdk_pixbuf_get_width (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->width);
 }
 
+/**
+ * gdk_pixbuf_get_height:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the height of a pixbuf.
+ *
+ * Return value: Height in pixels.
+ **/
 int
 gdk_pixbuf_get_height (GdkPixbuf *pixbuf)
 {
@@ -214,6 +276,14 @@ gdk_pixbuf_get_height (GdkPixbuf *pixbuf)
 	return (pixbuf->art_pixbuf->height);
 }
 
+/**
+ * gdk_pixbuf_get_rowstride:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the rowstride of a pixbuf, or the number of bytes between rows.
+ *
+ * Return value: Number of bytes between rows.
+ **/
 int
 gdk_pixbuf_get_rowstride (GdkPixbuf *pixbuf)
 {