Populated.

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

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

	* doc/gdk-pixbuf.signals: Put in the real names of signal
	arguments.

	* src/gdk-pixbuf-loader.c: Improved documentation comments.

12 files changed, 136 insertions, 109 deletions

diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf.signals b/docs/reference/gdk-pixbuf/gdk-pixbuf.signals
index d53d607821..82587ac38a 100644
--- a/docs/reference/gdk-pixbuf/gdk-pixbuf.signals
+++ b/docs/reference/gdk-pixbuf/gdk-pixbuf.signals
@@ -1,22 +1,22 @@
 <SIGNAL>
 <NAME>GdkPixbufLoader::area-updated</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
-gint  arg1
-gint  arg2
-gint  arg3
-gint  arg4
+GdkPixbufLoader *loader
+gint  x
+gint  y
+gint  width
+gint  height
 </SIGNAL>
 
 <SIGNAL>
 <NAME>GdkPixbufLoader::area-prepared</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
+GdkPixbufLoader *loader
 </SIGNAL>
 
 <SIGNAL>
 <NAME>GdkPixbufLoader::closed</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
+GdkPixbufLoader *loader
 </SIGNAL>
 
diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml
index ae55d3cc89..3c06008c91 100644
--- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml
@@ -86,8 +86,7 @@ Creating a pixbuf from image data that is already in memory.
 </para>
 
 @data: 
-@Returns: 
-<!--
+@Returns: <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
diff --git a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
index a333df963a..5659bc4457 100644
--- a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
@@ -31,8 +31,7 @@ Loading a pixbuf from a file.
 </para>
 
 @filename: 
-@Returns: 
-<!--
+@Returns: <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
index bed4d338db..930977219e 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
@@ -7,20 +7,23 @@ Application-driven image loading.
 <!-- ##### SECTION Long_Description ##### -->
   <para>
     #GdkPIxbufLoader provides a way for applications to drive the
-    process of loading an image.  
+    process of loading an image.  Applications can use this
+    functionality instead of gdk_pixbuf_new_from_file() when they need
+    to parse image data in small chunks, such as when reading it from
+    a network connection.
   </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+  <para>
+    gdk_pixbuf_new_from_file()
+  </para>
 
 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
-<para>
-
-</para>
+  <para>
+    Casts a #GtkObject to a #GdkPixbufLoader.
+  </para>
 
-@obj: 
+@obj: A GTK+ object.
 
 
 <!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
@@ -60,29 +63,40 @@ Application-driven image loading.
 
 
 <!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
-<para>
-
-</para>
+  <para>
+    This signal is emitted when a significant area of the image being
+    loaded has been updated.  Normally it means that a complete
+    scanline has been read in, but it could be a different area as
+    well.  Applications can use this signal to know when to repaint
+    areas of an image that is being loaded.
+  </para>
 
-@gdkpixbufloader: the object which received the signal.
-@arg1: 
-@arg2: 
-@arg3: 
-@arg4: 
+@loader: Loader which emitted the signal.
+@x: X offset of upper-left corner of the updated area.
+@y: Y offset of upper-left corner of the updated area.
+@width: Width of updated area.
+@height: Height of updated area.
 
 <!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
-<para>
-
-</para>
+  <para>
+    This signal is emitted when the pixbuf loader has been fed the
+    initial amount of data that is required to figure out the size and
+    format of the image that it will create.  After this signal is
+    emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to
+    fetch the partially-loaded pixbuf.
+  </para>
 
-@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
 
 <!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
-<para>
-
-</para>
+  <para>
+    This signal is emitted when gdk_pixbuf_loader_close() is called.
+    It can be used by different parts of an application to receive
+    notification when an image loader is closed by the code that
+    drives it.
+  </para>
 
-@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
 
 <!--
 Local variables:
@@ -90,3 +104,4 @@ mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 End:
 -->
+
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
index 87c60ba360..ff31dacb12 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
@@ -98,8 +98,7 @@ the image data.
 </para>
 
 @pixbuf: 
-@Returns: 
-<!--
+@Returns: <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
diff --git a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
index 9d8eb9627f..01966fa56f 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml
@@ -160,6 +160,20 @@ Canvas item to display #GdkPixbuf images.
     this yourself if you intend to keep the pixbuf structure around.
   </para>
 
+<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+  <para>
+    Indicates the width the pixbuf will be scaled to.  This argument
+    will only be used if the <link
+    linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
+    is %TRUE.  If the <link
+    linkend="GnomeCanvasPixbuf--width-pixels">width_pixels</link>
+    argument is %FALSE, the width will be taken to be in canvas units,
+    and thus will be scaled along with the canvas item's affine
+    transformation.  If width_pixels is %TRUE, the width will be taken
+    to be in pixels, and will visually remain a constant size even if
+    the item's affine transformation changes.
+  </para>
+
 <!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
   <para>
     Determines whether the <link
@@ -179,18 +193,13 @@ Canvas item to display #GdkPixbuf images.
     transformations.  The default is %FALSE.
   </para>
 
-<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
   <para>
-    Indicates the width the pixbuf will be scaled to.  This argument
+    Indicates the height the pixbuf will be scaled to.  This argument
     will only be used if the <link
-    linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
-    is %TRUE.  If the <link
-    linkend="GnomeCanvasPixbuf--width-pixels">width_pixels</link>
-    argument is %FALSE, the width will be taken to be in canvas units,
-    and thus will be scaled along with the canvas item's affine
-    transformation.  If width_pixels is %TRUE, the width will be taken
-    to be in pixels, and will visually remain a constant size even if
-    the item's affine transformation changes.
+    linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
+    is %TRUE.  Works in the same way as the <link
+    linkend="GnomeCanvasPixbuf--width">width</link> argument.
   </para>
 
 <!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
@@ -210,13 +219,13 @@ Canvas item to display #GdkPixbuf images.
     argument.  The default is %FALSE.
   </para>
 
-<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
   <para>
-    Indicates the height the pixbuf will be scaled to.  This argument
-    will only be used if the <link
-    linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
-    is %TRUE.  Works in the same way as the <link
-    linkend="GnomeCanvasPixbuf--width">width</link> argument.
+    Indicates the horizontal translation offset of the pixbuf item's
+    image.  This argument will only be used if the <link
+    linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument is %TRUE.
+    This offset may not actually appear horizontal, since it will be
+    affected by the item's affine transformation.
   </para>
 
 <!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
@@ -237,15 +246,21 @@ Canvas item to display #GdkPixbuf images.
     will change along with the item's affine transformation.
   </para>
 
-<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
   <para>
-    Indicates the horizontal translation offset of the pixbuf item's
-    image.  This argument will only be used if the <link
-    linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument is %TRUE.
-    This offset may not actually appear horizontal, since it will be
-    affected by the item's affine transformation.
+    Indicates the vertical translation offset of the pixbuf item's
+    image.  Works in the same way as the <link
+    linkend="GnomeCanvasPixbuf--x">x</link> argument.
   </para>
 
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
+
 <!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
   <para>
     Determines whether the <link
@@ -263,18 +278,3 @@ Canvas item to display #GdkPixbuf images.
     The default is %FALSE.
   </para>
 
-<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
-  <para>
-    Indicates the vertical translation offset of the pixbuf item's
-    image.  Works in the same way as the <link
-    linkend="GnomeCanvasPixbuf--x">x</link> argument.
-  </para>
-
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-
diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
index 04ee946324..845d2ceaf6 100644
--- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
@@ -33,8 +33,7 @@ Functions to perform reference counting on a #GdkPixbuf.
 
 </para>
 
-@pixbuf: 
-<!--
+@pixbuf: <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
diff --git a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
index 1a65d54198..6ed99c43fd 100644
--- a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml
@@ -96,8 +96,7 @@ In the future it will do full alpha compositing.
 @dest_y: 
 @width: 
 @height: 
-@alpha_threshold: 
-<!--
+@alpha_threshold: <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index e7a9ecde8f..31fcb963ed 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,12 @@
+1999-11-10  Federico Mena Quintero  <federico@redhat.com>
+
+	* doc/tmpl/gdk-pixbuf-loader.sgml: Populated.
+
+	* doc/gdk-pixbuf.signals: Put in the real names of signal
+	arguments.
+
+	* src/gdk-pixbuf-loader.c: Improved documentation comments.
+
 1999-11-10  Jonathan Blandford  <jrb@redhat.com>
 
 	* src/gdk-pixbuf-loader.c (gdk_pixbuf_loader_close): emit the
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 9557d90370..b139d4e1fc 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -295,7 +295,7 @@ gdk_pixbuf_new_from_file (const char *filename)
 
 /**
  * gdk_pixbuf_new_from_xpm_data:
- * @data: 
+ * @data: Pointer to inline XPM data.
  * 
  * Creates a new pixbuf by parsing XPM data in memory.  This data is commonly
  * the result of including an XPM file into a program's C source.
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 49f8688c2f..346074f367 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -307,15 +307,16 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, const gchar *buf, s
 /**
  * gdk_pixbuf_loader_write:
  * @loader: A pixbuf loader.
- * @buf: The image data.
- * @count: The length of @buf in bytes.
+ * @buf: Pointer to image data.
+ * @count: Length of the @buf buffer in bytes.
  *
- * This will load the next @size bytes of the image.  It will return TRUE if the
- * data was loaded successfully, and FALSE if an error occurred. In this case,
- * the loader will be closed, and will not accept further writes.
+ * This will cause a pixbuf loader to parse the next @count bytes of an image.
+ * It will return TRUE if the data was loaded successfully, and FALSE if an
+ * error occurred.  In the latter case, the loader will be closed, and will not
+ * accept further writes.
  *
- * Return value: Returns TRUE if the write was successful -- FALSE if the loader
- * cannot parse the buf.
+ * Return value: #TRUE if the write was successful, or #FALSE if the loader
+ * cannot parse the buffer.
  **/
 gboolean
 gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count)
@@ -354,14 +355,16 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count
  * gdk_pixbuf_loader_get_pixbuf:
  * @loader: A pixbuf loader.
  *
- * Gets the GdkPixbuf that the loader is currently loading.  If the loader
- * hasn't been enough data via gdk_pixbuf_loader_write, then NULL is returned.
- * Any application using this function should check for this value when it is
- * used.  The pixbuf returned will be the same in all future calls to the
- * loader, so simply calling a gdk_pixbuf_ref() should be sufficient to continue
- * using it.
+ * Queries the GdkPixbuf that a pixbuf loader is currently creating.  In general
+ * it only makes sense to call this function afer the "area_prepared" signal has
+ * been emitted by the loader; this means that enough data has been read to know
+ * the size of the image that will be allocated.  If the loader has not received
+ * enough data via gdk_pixbuf_loader_write(), then this function returns NULL.
+ * The returned pixbuf will be the same in all future calls to the loader, so
+ * simply calling gdk_pixbuf_ref() should be sufficient to continue using it.
  *
- * Return value: The GdkPixbuf that the loader is loading.
+ * Return value: The GdkPixbuf that the loader is creating, or NULL if not
+ * enough data has been read to determine how to create the image buffer.
  **/
 GdkPixbuf *
 gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
@@ -380,7 +383,8 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
  * gdk_pixbuf_loader_close:
  * @loader: A pixbuf loader.
  *
- * Tells the loader to stop accepting writes.
+ * Informs a pixbuf loader that no further writes with gdk_pixbuf_load_write()
+ * will occur, so that it can free its internal loading structures.
  **/
 void
 gdk_pixbuf_loader_close (GdkPixbufLoader *loader)
diff --git a/gtk/gdk-pixbuf-loader.c b/gtk/gdk-pixbuf-loader.c
index 49f8688c2f..346074f367 100644
--- a/gtk/gdk-pixbuf-loader.c
+++ b/gtk/gdk-pixbuf-loader.c
@@ -307,15 +307,16 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, const gchar *buf, s
 /**
  * gdk_pixbuf_loader_write:
  * @loader: A pixbuf loader.
- * @buf: The image data.
- * @count: The length of @buf in bytes.
+ * @buf: Pointer to image data.
+ * @count: Length of the @buf buffer in bytes.
  *
- * This will load the next @size bytes of the image.  It will return TRUE if the
- * data was loaded successfully, and FALSE if an error occurred. In this case,
- * the loader will be closed, and will not accept further writes.
+ * This will cause a pixbuf loader to parse the next @count bytes of an image.
+ * It will return TRUE if the data was loaded successfully, and FALSE if an
+ * error occurred.  In the latter case, the loader will be closed, and will not
+ * accept further writes.
  *
- * Return value: Returns TRUE if the write was successful -- FALSE if the loader
- * cannot parse the buf.
+ * Return value: #TRUE if the write was successful, or #FALSE if the loader
+ * cannot parse the buffer.
  **/
 gboolean
 gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count)
@@ -354,14 +355,16 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count
  * gdk_pixbuf_loader_get_pixbuf:
  * @loader: A pixbuf loader.
  *
- * Gets the GdkPixbuf that the loader is currently loading.  If the loader
- * hasn't been enough data via gdk_pixbuf_loader_write, then NULL is returned.
- * Any application using this function should check for this value when it is
- * used.  The pixbuf returned will be the same in all future calls to the
- * loader, so simply calling a gdk_pixbuf_ref() should be sufficient to continue
- * using it.
+ * Queries the GdkPixbuf that a pixbuf loader is currently creating.  In general
+ * it only makes sense to call this function afer the "area_prepared" signal has
+ * been emitted by the loader; this means that enough data has been read to know
+ * the size of the image that will be allocated.  If the loader has not received
+ * enough data via gdk_pixbuf_loader_write(), then this function returns NULL.
+ * The returned pixbuf will be the same in all future calls to the loader, so
+ * simply calling gdk_pixbuf_ref() should be sufficient to continue using it.
  *
- * Return value: The GdkPixbuf that the loader is loading.
+ * Return value: The GdkPixbuf that the loader is creating, or NULL if not
+ * enough data has been read to determine how to create the image buffer.
  **/
 GdkPixbuf *
 gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
@@ -380,7 +383,8 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
  * gdk_pixbuf_loader_close:
  * @loader: A pixbuf loader.
  *
- * Tells the loader to stop accepting writes.
+ * Informs a pixbuf loader that no further writes with gdk_pixbuf_load_write()
+ * will occur, so that it can free its internal loading structures.
  **/
 void
 gdk_pixbuf_loader_close (GdkPixbufLoader *loader)