Index: docs/reference/gtk/tmpl/gtkimage.sgml
===================================================================
--- docs/reference/gtk/tmpl/gtkimage.sgml	(revision 17248)
+++ docs/reference/gtk/tmpl/gtkimage.sgml	(working copy)
@@ -2,112 +2,26 @@
 GtkImage
 
 <!-- ##### SECTION Short_Description ##### -->
-A widget displaying an image
+
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The #GtkImage widget displays an image. Various kinds of object 
-can be displayed as an image; most typically, you would load a 
-#GdkPixbuf ("pixel buffer") from a file, and then display that. 
-There's a convenience function to do this, gtk_image_new_from_file(),
-used as follows:
-<informalexample><programlisting>
-  GtkWidget *image;
-  image = gtk_image_new_from_file ("myfile.png");
-</programlisting></informalexample>
-If the file isn't loaded successfully, the image will contain a
-"broken image" icon similar to that used in many web browsers.
-If you want to handle errors in loading the file yourself, 
-for example by displaying an error message, then load the image with
-gdk_pixbuf_new_from_file(), then create the #GtkImage with 
-gtk_image_new_from_pixbuf().
-</para>
-<para>
-The image file may contain an animation, if so the #GtkImage will 
-display an animation (#GdkPixbufAnimation) instead of a static image.
-</para>
-<para>
-#GtkImage is a subclass of #GtkMisc, which implies that you can 
-align it (center, left, right) and add padding to it, using 
-#GtkMisc methods.
-</para>
-<para>
-#GtkImage is a "no window" widget (has no #GdkWindow of its own), 
-so by default does not receive events. If you want to receive events
-on the image, such as button clicks, place the image inside a 
-#GtkEventBox, then connect to the event signals on the event box.
-<example>
-<title>Handling button press events on a 
-<structname>GtkImage</structname>.</title>
-<programlisting>
-  static gboolean
-  button_press_callback (GtkWidget      *event_box, 
-                         GdkEventButton *event,
-                         gpointer        data)
-  {
-    g_print ("Event box clicked at coordinates &percnt;f,&percnt;f\n", 
-             event->x, event->y);
-
-    /* Returning TRUE means we handled the event, so the signal 
-     * emission should be stopped (don't call any further 
-     * callbacks that may be connected). Return FALSE
-     * to continue invoking callbacks.
-     */
-    return TRUE;
-  }
-
-  static GtkWidget*
-  create_image (void)
-  {
-    GtkWidget *image;
-    GtkWidget *event_box;
-
-    image = gtk_image_new_from_file ("myfile.png");
-
-    event_box = gtk_event_box_new (<!-- -->);
-
-    gtk_container_add (GTK_CONTAINER (event_box), image);
-
-    g_signal_connect (G_OBJECT (event_box), 
-                      "button_press_event",
-                      G_CALLBACK (button_press_callback),
-                      image);
-
-    return image;
-  }
-</programlisting>
-</example>
-</para>
-<para>
-When handling events on the event box, keep in mind that coordinates
-in the image may be different from event box coordinates due to 
-the alignment and padding settings on the image (see #GtkMisc). 
-The simplest way to solve this is to set the alignment to 0.0
-(left/top), and set the padding to zero. Then the origin of 
-the image will be the same as the origin of the event box.
-</para>
-
-<para>
-Sometimes an application will want to avoid depending on external data
-files, such as image files. GTK+ comes with a program to avoid this,
-called <application>gdk-pixbuf-csource</application>. This program
-allows you to convert an image into a C variable declaration, which
-can then be loaded into a #GdkPixbuf using
-gdk_pixbuf_new_from_inline().
+
 </para>
 
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
-#GdkPixbuf
+
 </para>
 
+
 <!-- ##### SECTION Stability_Level ##### -->
 
 
 <!-- ##### STRUCT GtkImage ##### -->
 <para>
-This struct contain private data only and should be accessed by the functions
-below.
+
 </para>
 
 
@@ -173,24 +87,17 @@ below.
 
 <!-- ##### ENUM GtkImageType ##### -->
 <para>
-Describes the image data representation used by a #GtkImage. If you
-want to get the image from the widget, you can only get the
-currently-stored representation. e.g.  if the
-gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can
-call gtk_image_get_pixbuf() but not gtk_image_get_stock().  For empty
-images, you can request any storage type (call any of the "get"
-functions), but they will all return %NULL values.
-</para>
-
-@GTK_IMAGE_EMPTY: there is no image displayed by the widget
-@GTK_IMAGE_PIXMAP: the widget contains a #GdkPixmap
-@GTK_IMAGE_IMAGE: the widget contains a #GdkImage
-@GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
-@GTK_IMAGE_STOCK: the widget contains a stock icon name (see <xref linkend="gtk-Stock-Items"/>)
-@GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
-@GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
-@GTK_IMAGE_ICON_NAME: the widget contains a named icon. 
-  This image type was added in GTK+ 2.6
+
+</para>
+
+@GTK_IMAGE_EMPTY: 
+@GTK_IMAGE_PIXMAP: 
+@GTK_IMAGE_IMAGE: 
+@GTK_IMAGE_PIXBUF: 
+@GTK_IMAGE_STOCK: 
+@GTK_IMAGE_ICON_SET: 
+@GTK_IMAGE_ANIMATION: 
+@GTK_IMAGE_ICON_NAME: 
 
 <!-- ##### FUNCTION gtk_image_get_icon_set ##### -->
 <para>
@@ -436,29 +343,27 @@ functions), but they will all return %NU
 
 </para>
 
-@Returns: the #GtkImage
-<!-- # Unused Parameters # -->
-@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_image_set ##### -->
 <para>
-Sets the #GtkImage.
+
 </para>
 
-@image: a #GtkImage
-@val: a #GdkImage
-@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
+@image: 
+@val: 
+@mask: 
 
 
 <!-- ##### FUNCTION gtk_image_get ##### -->
 <para>
-Gets the #GtkImage.
+
 </para>
 
-@image: a #GtkImage
-@val: return location for a #GdkImage
-@mask: a #GdkBitmap that indicates which parts of the image should be transparent.
+@image: 
+@val: 
+@mask: 
 
 
 <!-- ##### FUNCTION gtk_image_set_pixel_size ##### -->
Index: gtk/gtkimage.c
===================================================================
--- gtk/gtkimage.c	(revision 17248)
+++ gtk/gtkimage.c	(working copy)
@@ -24,6 +24,98 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION: gtkimage
+ * @short_description: A widget displaying an image
+ * @title: GtkImage
+ * @see_also: #GdkPixbuf
+ *
+ * The #GtkImage widget displays an image. Various kinds of object 
+ * can be displayed as an image; most typically, you would load a 
+ * #GdkPixbuf ("pixel buffer") from a file, and then display that. 
+ * There's a convenience function to do this, gtk_image_new_from_file(),
+ * used as follows:
+ * <informalexample><programlisting>
+ *   GtkWidget *image;
+ *   image = gtk_image_new_from_file ("myfile.png");
+ * </programlisting></informalexample>
+ * If the file isn't loaded successfully, the image will contain a
+ * "broken image" icon similar to that used in many web browsers.
+ * If you want to handle errors in loading the file yourself, 
+ * for example by displaying an error message, then load the image with
+ * gdk_pixbuf_new_from_file(), then create the #GtkImage with 
+ * gtk_image_new_from_pixbuf().
+ * 
+ * The image file may contain an animation, if so the #GtkImage will 
+ * display an animation (#GdkPixbufAnimation) instead of a static image.
+ * 
+ * #GtkImage is a subclass of #GtkMisc, which implies that you can 
+ * align it (center, left, right) and add padding to it, using 
+ * #GtkMisc methods.
+ * 
+ * #GtkImage is a "no window" widget (has no #GdkWindow of its own), 
+ * so by default does not receive events. If you want to receive events
+ * on the image, such as button clicks, place the image inside a 
+ * #GtkEventBox, then connect to the event signals on the event box.
+ * <example>
+ * <title>Handling button press events on a 
+ * <structname>GtkImage</structname>.</title>
+ * <programlisting>
+ *   static gboolean
+ *   button_press_callback (GtkWidget      *event_box, 
+ *                          GdkEventButton *event,
+ *                          gpointer        data)
+ *   {
+ *     g_print ("Event box clicked at coordinates &percnt;f,&percnt;f\n", 
+ *              event->x, event->y);
+ * 
+ *     /<!-- -->* Returning TRUE means we handled the event, so the signal 
+ *      * emission should be stopped (don't call any further 
+ *      * callbacks that may be connected). Return FALSE
+ *      * to continue invoking callbacks.
+ *      *<!-- -->/
+ *     return TRUE;
+ *   }
+ * 
+ *   static GtkWidget*
+ *   create_image (void)
+ *   {
+ *     GtkWidget *image;
+ *     GtkWidget *event_box;
+ * 
+ *     image = gtk_image_new_from_file ("myfile.png");
+ * 
+ *     event_box = gtk_event_box_new (<!-- -->);
+ * 
+ *     gtk_container_add (GTK_CONTAINER (event_box), image);
+ * 
+ *     g_signal_connect (G_OBJECT (event_box), 
+ *                       "button_press_event",
+ *                       G_CALLBACK (button_press_callback),
+ *                       image);
+ * 
+ *     return image;
+ *   }
+ * </programlisting>
+ * </example>
+ * 
+ * When handling events on the event box, keep in mind that coordinates
+ * in the image may be different from event box coordinates due to 
+ * the alignment and padding settings on the image (see #GtkMisc). 
+ * The simplest way to solve this is to set the alignment to 0.0
+ * (left/top), and set the padding to zero. Then the origin of 
+ * the image will be the same as the origin of the event box.
+ * 
+ * Sometimes an application will want to avoid depending on external data
+ * files, such as image files. GTK+ comes with a program to avoid this,
+ * called <application>gdk-pixbuf-csource</application>. This program
+ * allows you to convert an image into a C variable declaration, which
+ * can then be loaded into a #GdkPixbuf using
+ * gdk_pixbuf_new_from_inline().
+ **/ 
+
+
+ 
 #include <config.h>
 #include <math.h>
 #include <string.h>
@@ -458,8 +550,8 @@ gtk_image_get_property (GObject     *obj
 
 /**
  * gtk_image_new_from_pixmap:
- * @pixmap: a #GdkPixmap, or %NULL
- * @mask: a #GdkBitmap, or %NULL
+ * @pixmap: a #GdkPixmap, or %NULL.
+ * @mask: a #GdkBitmap, or %NULL.
  * 
  * Creates a #GtkImage widget displaying @pixmap with a @mask.
  * A #GdkPixmap is a server-side image buffer in the pixel format of the
@@ -467,7 +559,7 @@ gtk_image_get_property (GObject     *obj
  * pixmap or mask; you still need to unref them if you own references.
  * #GtkImage will add its own reference rather than adopting yours.
  * 
- * Return value: a new #GtkImage
+ * Return value: a new #GtkImage.
  **/
 GtkWidget*
 gtk_image_new_from_pixmap (GdkPixmap *pixmap,
@@ -484,8 +576,8 @@ gtk_image_new_from_pixmap (GdkPixmap *pi
 
 /**
  * gtk_image_new_from_image:
- * @image: a #GdkImage, or %NULL
- * @mask: a #GdkBitmap, or %NULL 
+ * @image: a #GdkImage, or %NULL.
+ * @mask: a #GdkBitmap, or %NULL. 
  * 
  * Creates a #GtkImage widget displaying a @image with a @mask.
  * A #GdkImage is a client-side image buffer in the pixel format of the
@@ -494,7 +586,7 @@ gtk_image_new_from_pixmap (GdkPixmap *pi
  * image or mask; you still need to unref them if you own references.
  * #GtkImage will add its own reference rather than adopting yours.
  * 
- * Return value: a new #GtkImage
+ * Return value: a new #GtkImage.
  **/
 GtkWidget*
 gtk_image_new_from_image  (GdkImage  *gdk_image,
@@ -511,7 +603,7 @@ gtk_image_new_from_image  (GdkImage  *gd
 
 /**
  * gtk_image_new_from_file:
- * @filename: a filename
+ * @filename: a filename.
  * 
  * Creates a new #GtkImage displaying the file @filename. If the file
  * isn't found or can't be loaded, the resulting #GtkImage will
@@ -530,7 +622,7 @@ gtk_image_new_from_image  (GdkImage  *gd
  * image is not defined, it will be whatever is appropriate for
  * displaying the file.
  * 
- * Return value: a new #GtkImage
+ * Return value: a new #GtkImage.
  **/
 GtkWidget*
 gtk_image_new_from_file   (const gchar *filename)
@@ -546,7 +638,7 @@ gtk_image_new_from_file   (const gchar *
 
 /**
  * gtk_image_new_from_pixbuf:
- * @pixbuf: a #GdkPixbuf, or %NULL
+ * @pixbuf: a #GdkPixbuf, or %NULL.
  * 
  * Creates a new #GtkImage displaying @pixbuf.
  * The #GtkImage does not assume a reference to the
@@ -557,7 +649,7 @@ gtk_image_new_from_file   (const gchar *
  * #GtkImage created will not react to state changes.  Should you want that, you
  * should use gtk_image_new_from_icon_set().
  * 
- * Return value: a new #GtkImage
+ * Return value: a new #GtkImage.
  **/
 GtkWidget*
 gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf)
@@ -573,8 +665,8 @@ gtk_image_new_from_pixbuf (GdkPixbuf *pi
 
 /**
  * gtk_image_new_from_stock:
- * @stock_id: a stock icon name
- * @size: a stock icon size
+ * @stock_id: a stock icon name.
+ * @size: a stock icon size.
  * 
  * Creates a #GtkImage displaying a stock icon. Sample stock icon
  * names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. Sample stock sizes
@@ -583,7 +675,7 @@ gtk_image_new_from_pixbuf (GdkPixbuf *pi
  * You can register your own stock icon names, see
  * gtk_icon_factory_add_default() and gtk_icon_factory_add().
  * 
- * Return value: a new #GtkImage displaying the stock icon
+ * Return value: a new #GtkImage displaying the stock icon.
  **/
 GtkWidget*
 gtk_image_new_from_stock (const gchar    *stock_id,
@@ -600,8 +692,8 @@ gtk_image_new_from_stock (const gchar   
 
 /**
  * gtk_image_new_from_icon_set:
- * @icon_set: a #GtkIconSet
- * @size: a stock icon size
+ * @icon_set: a #GtkIconSet.
+ * @size: a stock icon size.
  *
  * Creates a #GtkImage displaying an icon set. Sample stock sizes are
  * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using
@@ -616,7 +708,7 @@ gtk_image_new_from_stock (const gchar   
  * #GtkImage will add its own reference rather than adopting yours.
  * 
  * 
- * Return value: a new #GtkImage
+ * Return value: a new #GtkImage.
  **/
 GtkWidget*
 gtk_image_new_from_icon_set (GtkIconSet     *icon_set,
@@ -633,7 +725,7 @@ gtk_image_new_from_icon_set (GtkIconSet 
 
 /**
  * gtk_image_new_from_animation:
- * @animation: an animation
+ * @animation: an animation.
  * 
  * Creates a #GtkImage displaying the given animation.
  * The #GtkImage does not assume a reference to the
@@ -645,7 +737,7 @@ gtk_image_new_from_icon_set (GtkIconSet 
  * keep in mind that the animation will only be shown if the main loop
  * is not busy with something that has a higher priority.
  *
- * Return value: a new #GtkImage widget
+ * Return value: a new #GtkImage widget.
  **/
 GtkWidget*
 gtk_image_new_from_animation (GdkPixbufAnimation *animation)
@@ -663,15 +755,15 @@ gtk_image_new_from_animation (GdkPixbufA
 
 /**
  * gtk_image_new_from_icon_name:
- * @icon_name: an icon name
- * @size: a stock icon size
+ * @icon_name: an icon name.
+ * @size: a stock icon size.
  * 
  * Creates a #GtkImage displaying an icon from the current icon theme.
  * If the icon name isn't known, a "broken image" icon will be
  * displayed instead.  If the current icon theme is changed, the icon
  * will be updated appropriately.
  * 
- * Return value: a new #GtkImage displaying the themed icon
+ * Return value: a new #GtkImage displaying the themed icon.
  *
  * Since: 2.6
  **/
@@ -690,12 +782,11 @@ gtk_image_new_from_icon_name (const gcha
 
 /**
  * gtk_image_set_from_pixmap:
- * @image: a #GtkImage
- * @pixmap: a #GdkPixmap or %NULL
- * @mask: a #GdkBitmap or %NULL
+ * @image: a #GtkImage.
+ * @pixmap: a #GdkPixmap or %NULL.
+ * @mask: a #GdkBitmap or %NULL.
  *
  * See gtk_image_new_from_pixmap() for details.
- * 
  **/
 void
 gtk_image_set_from_pixmap (GtkImage  *image,
@@ -742,12 +833,11 @@ gtk_image_set_from_pixmap (GtkImage  *im
 
 /**
  * gtk_image_set_from_image:
- * @image: a #GtkImage
- * @gdk_image: a #GdkImage or %NULL
- * @mask: a #GdkBitmap or %NULL
+ * @image: a #GtkImage.
+ * @gdk_image: a #GdkImage or %NULL.
+ * @mask: a #GdkBitmap or %NULL.
  *
  * See gtk_image_new_from_image() for details.
- * 
  **/
 void
 gtk_image_set_from_image  (GtkImage  *image,
@@ -794,11 +884,10 @@ gtk_image_set_from_image  (GtkImage  *im
 
 /**
  * gtk_image_set_from_file:
- * @image: a #GtkImage
- * @filename: a filename or %NULL
+ * @image: a #GtkImage.
+ * @filename: a filename or %NULL.
  *
  * See gtk_image_new_from_file() for details.
- * 
  **/
 void
 gtk_image_set_from_file   (GtkImage    *image,
@@ -851,11 +940,10 @@ gtk_image_set_from_file   (GtkImage    *
 
 /**
  * gtk_image_set_from_pixbuf:
- * @image: a #GtkImage
- * @pixbuf: a #GdkPixbuf or %NULL
+ * @image: a #GtkImage.
+ * @pixbuf: a #GdkPixbuf or %NULL.
  *
  * See gtk_image_new_from_pixbuf() for details. 
- * 
  **/
 void
 gtk_image_set_from_pixbuf (GtkImage  *image,
@@ -890,12 +978,11 @@ gtk_image_set_from_pixbuf (GtkImage  *im
 
 /**
  * gtk_image_set_from_stock:
- * @image: a #GtkImage
- * @stock_id: a stock icon name
- * @size: a stock icon size
+ * @image: a #GtkImage.
+ * @stock_id: a stock icon name.
+ * @size: a stock icon size.
  *
  * See gtk_image_new_from_stock() for details.
- * 
  **/
 void
 gtk_image_set_from_stock  (GtkImage       *image,
@@ -934,12 +1021,11 @@ gtk_image_set_from_stock  (GtkImage     
 
 /**
  * gtk_image_set_from_icon_set:
- * @image: a #GtkImage
- * @icon_set: a #GtkIconSet
- * @size: a stock icon size
+ * @image: a #GtkImage.
+ * @icon_set: a #GtkIconSet.
+ * @size: a stock icon size.
  *
  * See gtk_image_new_from_icon_set() for details.
- * 
  **/
 void
 gtk_image_set_from_icon_set  (GtkImage       *image,
@@ -975,8 +1061,8 @@ gtk_image_set_from_icon_set  (GtkImage  
 
 /**
  * gtk_image_set_from_animation:
- * @image: a #GtkImage
- * @animation: the #GdkPixbufAnimation
+ * @image: a #GtkImage.
+ * @animation: the #GdkPixbufAnimation.
  * 
  * Causes the #GtkImage to display the given animation (or display
  * nothing, if you set the animation to %NULL).
@@ -1016,9 +1102,9 @@ gtk_image_set_from_animation (GtkImage  
 
 /**
  * gtk_image_set_from_icon_name:
- * @image: a #GtkImage
- * @icon_name: an icon name
- * @size: an icon size
+ * @image: a #GtkImage.
+ * @icon_name: an icon name.
+ * @size: an icon size.
  *
  * See gtk_image_new_from_icon_name() for details.
  * 
@@ -1061,13 +1147,13 @@ gtk_image_set_from_icon_name  (GtkImage 
 
 /**
  * gtk_image_get_storage_type:
- * @image: a #GtkImage
+ * @image: a #GtkImage.
  * 
  * Gets the type of representation being used by the #GtkImage
  * to store image data. If the #GtkImage has no image data,
  * the return value will be %GTK_IMAGE_EMPTY.
  * 
- * Return value: image representation being used
+ * Return value: image representation being used.
  **/
 GtkImageType
 gtk_image_get_storage_type (GtkImage *image)
@@ -1079,16 +1165,15 @@ gtk_image_get_storage_type (GtkImage *im
 
 /**
  * gtk_image_get_pixmap:
- * @image: a #GtkImage
- * @pixmap: location to store the pixmap, or %NULL
- * @mask: location to store the mask, or %NULL
+ * @image: a #GtkImage.
+ * @pixmap: location to store the pixmap, or %NULL.
+ * @mask: location to store the mask, or %NULL.
  *
  * Gets the pixmap and mask being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
  * %GTK_IMAGE_PIXMAP (see gtk_image_get_storage_type()).
  * The caller of this function does not own a reference to the
  * returned pixmap and mask.
- * 
  **/
 void
 gtk_image_get_pixmap (GtkImage   *image,
@@ -1108,9 +1193,9 @@ gtk_image_get_pixmap (GtkImage   *image,
 
 /**
  * gtk_image_get_image:
- * @image: a #GtkImage
- * @gdk_image: return location for a #GtkImage
- * @mask: return location for a #GdkBitmap
+ * @image: a #GtkImage.
+ * @gdk_image: return location for a #GtkImage.
+ * @mask: return location for a #GdkBitmap.
  * 
  * Gets the #GdkImage and mask being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
@@ -1136,8 +1221,7 @@ gtk_image_get_image  (GtkImage   *image,
 
 /**
  * gtk_image_get_pixbuf:
- * @image: a #GtkImage
- *
+ * @image: a #GtkImage.
  *
  * Gets the #GdkPixbuf being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
@@ -1145,7 +1229,7 @@ gtk_image_get_image  (GtkImage   *image,
  * The caller of this function does not own a reference to the
  * returned pixbuf.
  * 
- * Return value: the displayed pixbuf, or %NULL if the image is empty
+ * Return value: the displayed pixbuf, or %NULL if the image is empty.
  **/
 GdkPixbuf*
 gtk_image_get_pixbuf (GtkImage *image)
@@ -1162,16 +1246,15 @@ gtk_image_get_pixbuf (GtkImage *image)
 
 /**
  * gtk_image_get_stock:
- * @image: a #GtkImage
- * @stock_id: place to store a stock icon name
- * @size: place to store a stock icon size
+ * @image: a #GtkImage.
+ * @stock_id: place to store a stock icon name.
+ * @size: place to store a stock icon size.
  *
  * Gets the stock icon name and size being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
  * %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()).
  * The returned string is owned by the #GtkImage and should not
  * be freed.
- * 
  **/
 void
 gtk_image_get_stock  (GtkImage        *image,
@@ -1194,14 +1277,13 @@ gtk_image_get_stock  (GtkImage        *i
 
 /**
  * gtk_image_get_icon_set:
- * @image: a #GtkImage
- * @icon_set: location to store a #GtkIconSet
- * @size: location to store a stock icon size
+ * @image: a #GtkImage.
+ * @icon_set: location to store a #GtkIconSet.
+ * @size: location to store a stock icon size.
  *
  * Gets the icon set and size being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
  * %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()).
- * 
  **/
 void
 gtk_image_get_icon_set  (GtkImage        *image,
@@ -1221,8 +1303,7 @@ gtk_image_get_icon_set  (GtkImage       
 
 /**
  * gtk_image_get_animation:
- * @image: a #GtkImage
- *
+ * @image: a #GtkImage.
  *
  * Gets the #GdkPixbufAnimation being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
@@ -1230,7 +1311,7 @@ gtk_image_get_icon_set  (GtkImage       
  * The caller of this function does not own a reference to the
  * returned animation.
  * 
- * Return value: the displayed animation, or %NULL if the image is empty
+ * Return value: the displayed animation, or %NULL if the image is empty.
  **/
 GdkPixbufAnimation*
 gtk_image_get_animation (GtkImage *image)
@@ -1248,9 +1329,9 @@ gtk_image_get_animation (GtkImage *image
 
 /**
  * gtk_image_get_icon_name:
- * @image: a #GtkImage
- * @icon_name: place to store an icon name
- * @size: place to store an icon size
+ * @image: a #GtkImage.
+ * @icon_name: place to store an icon name.
+ * @size: place to store an icon size.
  *
  * Gets the icon name and size being displayed by the #GtkImage.
  * The storage type of the image must be %GTK_IMAGE_EMPTY or
@@ -1292,6 +1373,15 @@ gtk_image_new (void)
   return g_object_new (GTK_TYPE_IMAGE, NULL);
 }
 
+/**
+ * gtk_image_set:
+ * @image: a #GtkImage.
+ * @val: a #GdkImage.
+ * @mask: a #GdkBitmap that indicates which parts of the image should be transparent.
+ *
+ * Sets the #GtkImage.
+ **/
+
 void
 gtk_image_set (GtkImage  *image,
 	       GdkImage  *val,
@@ -1302,6 +1392,14 @@ gtk_image_set (GtkImage  *image,
   gtk_image_set_from_image (image, val, mask);
 }
 
+/**
+ * gtk_image_get:
+ * @image: a #GtkImage.
+ * @val: return location for a #GdkImage.
+ * @mask: a #GdkBitmap that indicates which parts of the image should be transparent.
+ *
+ * Gets the #GtkImage.
+ **/
 void
 gtk_image_get (GtkImage   *image,
 	       GdkImage  **val,
@@ -1927,7 +2025,7 @@ gtk_image_reset (GtkImage *image)
 
 /**
  * gtk_image_clear:
- * @image: a #GtkImage
+ * @image: a #GtkImage.
  *
  * Resets the image to be empty.
  *
@@ -2046,8 +2144,8 @@ gtk_image_update_size (GtkImage *image,
 
 /**
  * gtk_image_set_pixel_size:
- * @image: a #GtkImage
- * @pixel_size: the new pixel size
+ * @image: a #GtkImage.
+ * @pixel_size: the new pixel size.
  * 
  * Sets the pixel size to use for named icons. If the pixel size is set
  * to a value != -1, it is used instead of the icon size set by
@@ -2086,7 +2184,7 @@ gtk_image_set_pixel_size (GtkImage *imag
 
 /**
  * gtk_image_get_pixel_size:
- * @image: a #GtkImage
+ * @image: a #GtkImage.
  * 
  * Gets the pixel size used for named icons.
  *
Index: gtk/gtkimage.h
===================================================================
--- gtk/gtkimage.h	(revision 17248)
+++ gtk/gtkimage.h	(working copy)
@@ -34,6 +34,11 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GtkImage:
+ *
+ * This struct contain private data only and should be accessed by the functions below.
+ **/
 #define GTK_TYPE_IMAGE                  (gtk_image_get_type ())
 #define GTK_IMAGE(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_IMAGE, GtkImage))
 #define GTK_IMAGE_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_IMAGE, GtkImageClass))
@@ -92,6 +97,25 @@ struct _GtkImageIconNameData
   guint theme_change_id;
 };
 
+/**
+ * GtkImageType:
+ * @GTK_IMAGE_EMPTY: there is no image displayed by the widget.
+ * @GTK_IMAGE_PIXMAP: the widget contains a #GdkPixmap.
+ * @GTK_IMAGE_IMAGE: the widget contains a #GdkImage.
+ * @GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf.
+ * @GTK_IMAGE_STOCK: the widget contains a stock icon name (see <xref linkend="gtk-Stock-Items"/>).
+ * @GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet.
+ * @GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation.
+ * @GTK_IMAGE_ICON_NAME: the widget contains a named icon. This image type was added in GTK+ 2.6.
+ *
+ * Describes the image data representation used by a #GtkImage. If you
+ * want to get the image from the widget, you can only get the
+ * currently-stored representation. e.g.  if the
+ * gtk_image_get_storage_type() returns #GTK_IMAGE_PIXBUF, then you can
+ * call gtk_image_get_pixbuf() but not gtk_image_get_stock().  For empty
+ * images, you can request any storage type (call any of the "get"
+ * functions), but they will all return %NULL values.
+ **/
 typedef enum
 {
   GTK_IMAGE_EMPTY,
