Fix docs. (#66383)

        * gtk/gtklabel.c: Fix docs. (#66383)

        * gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs.
        (#66278, #66280)

        * gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
        gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)

        * gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
        Don't emit a g_warning() about being deprecated. (#66208)

        * gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.

        * gtk/gtkcontainer.c: Doc fixes.

        * gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.

        * gtk/gtkstyle.c (gtk_style_attach): Add docs.

        * gdk-pixbuf.h (gdk_pixbuf_ref, gdk_pixbuf_unref,
        gdk_pixbuf_animation_ref, gdk_pixbuf_animation_unref):
        Deprecate. (#66208)

        * gtk/tmpl/gtklabel.sgml: Remove redundant docs. (#66383)

        * gtk/tree_widget.sgml: Typo fix. (#66256)

        * gdk-pixbuf/Makefile.am (SCAN_OPTIONS): Add --deprecated-guards.

        * gtk/tmpl/gtktext.sgml, gtk/tmpl/gtktree.sgml,
        gtk/tmpl/gtktreeitem.sgml: Updates.

24 files changed, 371 insertions, 216 deletions

diff --git a/ChangeLog b/ChangeLog
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-0
+++ b/ChangeLog.pre-2-0
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-2
+++ b/ChangeLog.pre-2-2
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 63162af36..2a9d5e80d 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,24 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtklabel.c: Fix docs. (#66383)
+
+	* gtk/gtkbbox.c (gtk_button_box_set_child_secondary): Fix docs. 
+     	(#66278, #66280)
+	
+	* gdk/gdkwindow.h (gdk_window_get_deskrelative_origin),
+	gdk/gdkimage.h (gdk_image_get): Deprecate. (#66208)
+
+	* gtk/gtkcolorsel.c (gtk_color_selection_set_update_policy):
+	Don't emit a g_warning() about being deprecated. (#66208)	
+
+	* gtk/gtkaccellabel.c (gtk_accel_label_set_accel_widget): Add docs.
+
+	* gtk/gtkcontainer.c: Doc fixes.
+	
+	* gtk/gtkliststore.c (gtk_list_store_clear): Add docs; misc doc fixes.
+
+	* gtk/gtkstyle.c (gtk_style_attach): Add docs.
+
 2001-12-05  Sven Neumann  <sven@gimp.org>
 
 	* gtk/gtkwidget.c (gtk_widget_reset_shapes): close comment.
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e329293b7..62ed5c63d 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2001-12-06  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/tmpl/gtklabel.sgml: Remove redundant docs. (#66383)
+
+	* gtk/tree_widget.sgml: Typo fix. (#66256)
+
+	* gdk-pixbuf/Makefile.am (SCAN_OPTIONS): Add --deprecated-guards.
+	
+	* gtk/tmpl/gtktext.sgml, gtk/tmpl/gtktree.sgml, 
+	gtk/tmpl/gtktreeitem.sgml: Updates.
+
 2001-12-04  Matthias Clasen  <matthiasc@poet.de>
 
 	* gtk/tmpl/gtkwidget.sgml: Updates.
diff --git a/docs/reference/gdk-pixbuf/Makefile.am b/docs/reference/gdk-pixbuf/Makefile.am
index dd781216d..4d1361cdb 100644
--- a/docs/reference/gdk-pixbuf/Makefile.am
+++ b/docs/reference/gdk-pixbuf/Makefile.am
@@ -10,7 +10,7 @@ DOC_MAIN_SGML_FILE=gdk-pixbuf.sgml
 DOC_SOURCE_DIR=../../../gdk-pixbuf
 
 # Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib
+SCAN_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib --deprecated-guards="GDK_PIXBUF_ENABLE_BROKEN|GDK_PIXBUF_DISABLE_DEPRECATED"
 
 # Extra options to supply to gtkdoc-mkdb
 MKDB_OPTIONS=--sgml-mode --source-dir=../../../contrib/gdk-pixbuf-xlib
diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml
index 3c01f8abb..2f9f2c8bb 100644
--- a/docs/reference/gtk/tmpl/gtklabel.sgml
+++ b/docs/reference/gtk/tmpl/gtklabel.sgml
@@ -5,45 +5,41 @@ GtkLabel
 A widget that displays a small to medium amount of text.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>

-The #GtkLabel widget is usually used directly by the programmer to display

-word(s) describing an adjacent widget or its use.  It is also used internally

-by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which

-use text.

+<para>
+The #GtkLabel widget is usually used directly by the programmer to display
+word(s) describing an adjacent widget or its use.  It is also used internally
+by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which
+use text.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>

-

+<para>
+
 </para>
 
 <!-- ##### STRUCT GtkLabel ##### -->
-<para>

-This should not be accessed directly.  Use the accessor functions as

-described below.

+<para>
+This should not be accessed directly.  Use the accessor functions as
+described below.
 </para>
 
 
 <!-- ##### FUNCTION gtk_label_new ##### -->
-<para>

-Creates a new label with the given string of text inside it.  You can

-pass NULL to get an empty label widget.

+<para>
+
 </para>
 
-@str: The string you want to display in the #GtkLabel
-@Returns: The newly allocated #GtkLabel widget
+@str: 
+@Returns:
 
 
 <!-- ##### FUNCTION gtk_label_set_text ##### -->
-<para>

-Sets the text within the #GtkLabel widget.  It overwrites any text that

-was there before.  Note that underlines that were there before do not

-get overwritten.  If you want to erase underlines just send NULL to

-gtk_label_set_pattern().

+<para>
+
 </para>
 
-@label: The #GtkLabel you want to set the text for.
-@str: The text you want to add.
+@label: 
+@str: 
 
 
 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
@@ -74,11 +70,11 @@ gtk_label_set_pattern().
 
 
 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
-<para>

-The pattern of underlines you want under the existing text within the

-#GtkLabel widget.  For example if the current text of the label says

-&quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline

-&quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.

+<para>
+The pattern of underlines you want under the existing text within the
+#GtkLabel widget.  For example if the current text of the label says
+&quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
+&quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 </para>
 
 @label: The #GtkLabel you want to set the pattern to.
@@ -86,22 +82,19 @@ The pattern of underlines you want under the existing text within the
 
 
 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
-<para>

-Set where the text within the #GtkLabel will align to.  This can be one of

-four values: GTK_JUSTIFY_LEFT, GTK_JUSTIFY_RIGHT, GTK_JUSTIFY_CENTER,

-and GTK_JUSTIFY_FILL.  GTK_JUSTIFY_CENTER is the default value when the

-widget is first created with gtk_label_new().

+<para>
+
 </para>
 
-@label: The #GtkLabel widget you want to set justification for.
-@jtype: The #GtkJustification type as described above.
+@label: 
+@jtype: 
 
 
 <!-- ##### FUNCTION gtk_label_get ##### -->
-<para>

-Gets the current string of text within the #GtkLabel and writes it to

-the given str argument.  It does not make a copy of this string so you

-must not write to it.

+<para>
+Gets the current string of text within the #GtkLabel and writes it to
+the given @str argument.  It does not make a copy of this string so you
+must not write to it.
 </para>
 
 @label: The #GtkLabel widget you want to get the text from.
@@ -109,12 +102,12 @@ must not write to it.
 
 
 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
-<para>

-Parses the given string for underscores and converts the next

-character to an underlined character.  The last character that

-was underlined will have its lower-cased accelerator keyval returned  (i.e.

-&quot;_File&quot; would return the keyval for &quot;f&quot;.  This is

-probably only used within the Gtk+ library itself for menu items and such.

+<para>
+Parses the given string for underscores and converts the next
+character to an underlined character.  The last character that
+was underlined will have its lower-cased accelerator keyval returned  (i.e.
+&quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
+probably only used within the Gtk+ library itself for menu items and such.
 </para>
 
 @label: The #GtkLabel you want to affect.
@@ -123,20 +116,18 @@ probably only used within the Gtk+ library itself for menu items and such.
 
 
 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
-<para>

-Toggles line wrapping within the #GtkLabel widget.  TRUE makes it break

-lines if text exceeds the widget's size.  FALSE lets the text get cut off

-by the edge of the widget if it exceeds the widget size.

+<para>
+
 </para>
 
-@label: The #GtkLabel you want to set line wrapping for.
-@wrap: TRUE turns it on; FALSE turns it off.
+@label: 
+@wrap: 
 
 
 <!-- ##### MACRO gtk_label_set ##### -->
-<para>

-Aliases gtk_label_set_text.  Probably used for backward compatibility with

-Gtk+ 1.0.x.

+<para>
+Aliases gtk_label_set_text().  Probably used for backward compatibility with
+Gtk+ 1.0.x.
 </para>
 
 
@@ -222,8 +213,6 @@ Gtk+ 1.0.x.
 
 @label: 
 @str: 
-<!-- # Unused Parameters # -->
-@string: 
 
 
 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
@@ -362,8 +351,8 @@ Gtk+ 1.0.x.
 @arg1: 
 
 <!-- ##### ARG GtkLabel:label ##### -->
-<para>

-The actual label text.  Do not write to this pointer, it is not copied.

+<para>
+The actual label text.  Do not write to this pointer, it is not copied.
 </para>
 
 <!-- ##### ARG GtkLabel:attributes ##### -->
@@ -382,14 +371,14 @@ The actual label text.  Do not write to this pointer, it is not copied.
 </para>
 
 <!-- ##### ARG GtkLabel:justify ##### -->
-<para>

-The #GtkJustification setting.  See gtk_label_set_justify() for more info.

+<para>
+The #GtkJustification setting.  See gtk_label_set_justify() for more info.
 </para>
 
 <!-- ##### ARG GtkLabel:pattern ##### -->
-<para>

-The pattern of underlines under the existing text.  Do not change the

-pointer, it isn't copied.

+<para>
+The pattern of underlines under the existing text.  Do not change the
+pointer, it isn't copied.
 </para>
 
 <!-- ##### ARG GtkLabel:wrap ##### -->
diff --git a/docs/reference/gtk/tmpl/gtktext.sgml b/docs/reference/gtk/tmpl/gtktext.sgml
index f7d4e3f18..932742d72 100644
--- a/docs/reference/gtk/tmpl/gtktext.sgml
+++ b/docs/reference/gtk/tmpl/gtktext.sgml
@@ -2,10 +2,10 @@
 GtkText
 
 <!-- ##### SECTION Short_Description ##### -->
-deprecated text widget, use #GtkTextView instead
+Deprecated text widget, use #GtkTextView instead.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>

+<para>
 <warning>
 <para>
 #GtkText is deprecated and unsupported. It is known to be
@@ -13,54 +13,40 @@ buggy. To use it, you must define the symbol %GTK_ENABLE_BROKEN
 prior to including the GTK+ header files. Use #GtkTextView instead.
 </para>
 </warning>
-A #GtkText widget allows one to display any given text and manipulate it

-by deleting from one point to another, selecting a region, and various

-other functions as outlined below.  It is inherited from #GtkEditable.

+A #GtkText widget allows one to display any given text and manipulate it
+by deleting from one point to another, selecting a region, and various
+other functions as outlined below.  It is inherited from #GtkEditable.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>

-

+<para>
+
 </para>
 
 <!-- ##### STRUCT GtkText ##### -->
-<para>

-Most of the #GtkText-struct struct members should not be accessed directly.

-Listed below are a few exceptions and how to use them.

-

-<informaltable pgwide=1 frame="none" role="struct">

-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">

-<tbody>

-

-<row>

-<entry>GtkAdjustment *hadj;</entry>

-<entry>Allows you to see the state of an attached horizontal #GtkScrollbar.

-See #GtkAdjustment for more info. This allows easy access to the adjustments

-of the #GtkText struct without having to keep track of ones that you initialize

-at widget creation.</entry>

-</row>

-

-<row>

-<entry>GtkAdjustment *vadj;</entry>

-<entry>Same as hadj except it involves the vertical #GtkScrollbar.</entry>

-</row>

-

-</tbody></tgroup></informaltable>

-

+<para>
+Most of the #GtkText-struct struct members should not be accessed directly.
+Listed below are a few exceptions and how to use them.
 </para>
 
+@hadj: Allows you to see the state of an attached horizontal #GtkScrollbar.
+  See #GtkAdjustment for more info. This allows easy access to the adjustments
+  of the #GtkText struct without having to keep track of ones that you 
+  initialize at widget creation.
+@vadj: Same as @hadj except it involves the vertical #GtkScrollbar.
+
 
 <!-- ##### STRUCT GtkTextFont ##### -->
-<para>

-Internal #GtkText data type.

-<!-- Pretty sure.. declared in gtktext.c -->

+<para>
+Internal #GtkText data type.
+<!-- Pretty sure.. declared in gtktext.c -->
 </para>
 
 
 <!-- ##### STRUCT GtkPropertyMark ##### -->
-<para>

-Internal #GtkText data type.  Should not be access directly.

-<!-- FIXME: unsure about this  -->

+<para>
+Internal #GtkText data type.  Should not be accessed directly.
+<!-- FIXME: unsure about this  -->
 </para>
 
 @property: 
@@ -68,12 +54,12 @@ Internal #GtkText data type.  Should not be access directly.
 @index: 
 
 <!-- ##### FUNCTION gtk_text_new ##### -->
-<para>

-Creates a new #GtkText widget, initialized with the given pointers to

-#GtkAdjustments.  These pointers can be used to track the viewing position

-of the #GtkText widget.  Passing NULL to either or both of them will make

-the #GtkText create it's own.  You can set these later with the function

-<function>gtk_text_set_adjustment()</function>

+<para>
+Creates a new #GtkText widget, initialized with the given pointers to
+#GtkAdjustments.  These pointers can be used to track the viewing position
+of the #GtkText widget.  Passing %NULL to either or both of them will make
+the #GtkText create it's own.  You can set these later with the function
+gtk_text_set_adjustment().
 </para>
 
 @hadj: horizontal adjustment.
@@ -82,10 +68,10 @@ the #GtkText create it's own.  You can set these later with the function
 
 
 <!-- ##### FUNCTION gtk_text_set_editable ##### -->
-<para>

-Set whether the #GtkText widget can be edited by the user or not.  This

-still allows you the programmer to make changes with the various #GtkText

-functions.

+<para>
+Sets whether the #GtkText widget can be edited by the user or not.  This
+still allows you the programmer to make changes with the various #GtkText
+functions.
 </para>
 
 @text: the #GtkText widget
@@ -93,9 +79,9 @@ functions.
 
 
 <!-- ##### FUNCTION gtk_text_set_word_wrap ##### -->
-<para>

-Sets whether the #GtkText widget wraps words down to the next line if it

-can't be completed on the current line.

+<para>
+Sets whether the #GtkText widget wraps words down to the next line if it
+can't be completed on the current line.
 </para>
 
 @text: the #GtkText widget
@@ -103,12 +89,12 @@ can't be completed on the current line.
 
 
 <!-- ##### FUNCTION gtk_text_set_line_wrap ##### -->
-<para>

-Controls how #GtkText handles long lines of continuous text.  If line wrap

-is on, the line is broken when it reaches the extent of the #GtkText widget

-viewing area and the rest is displayed on the next line.  If it is not set,

-the line continues regardless size of current viewing area.  Similar to word

-wrap but it disregards word boundaries.

+<para>
+Controls how #GtkText handles long lines of continuous text.  If line wrap
+is on, the line is broken when it reaches the extent of the #GtkText widget
+viewing area and the rest is displayed on the next line.  If it is not set,
+the line continues regardless size of current viewing area.  Similar to word
+wrap but it disregards word boundaries.
 </para>
 
 @text: the #GtkText widget
@@ -116,9 +102,9 @@ wrap but it disregards word boundaries.
 
 
 <!-- ##### FUNCTION gtk_text_set_adjustments ##### -->
-<para>

-Allows you to set #GtkAdjustment pointers which in turn allows you to

-keep track of the viewing position of the #GtkText widget.

+<para>
+Allows you to set #GtkAdjustment pointers which in turn allows you to
+keep track of the viewing position of the #GtkText widget.
 </para>
 
 @text: the #GtkText widget
@@ -127,10 +113,10 @@ keep track of the viewing position of the #GtkText widget.
 
 
 <!-- ##### FUNCTION gtk_text_set_point ##### -->
-<para>

-Sets the cursor at the given point.  In this case a point constitutes

-the number of characters from the extreme upper left corner of the #GtkText

-widget.

+<para>
+Sets the cursor at the given point.  In this case a point constitutes
+the number of characters from the extreme upper left corner of the #GtkText
+widget.
 </para>
 
 @text: the #GtkText widget
@@ -138,9 +124,9 @@ widget.
 
 
 <!-- ##### FUNCTION gtk_text_get_point ##### -->
-<para>

-Gets the current position of the cursor as the number of characters from

-the upper left corner of the #GtkText widget.

+<para>
+Gets the current position of the cursor as the number of characters from
+the upper left corner of the #GtkText widget.
 </para>
 
 @text: the #GtkText widget
@@ -148,9 +134,9 @@ the upper left corner of the #GtkText widget.
 
 
 <!-- ##### FUNCTION gtk_text_get_length ##### -->
-<para>

-Returns the length of the all the text contained within the #GtkText widget;

-disregards current point position.

+<para>
+Returns the length of the all the text contained within the #GtkText widget;
+disregards current point position.
 </para>
 
 @text: the #GtkText widget
@@ -158,28 +144,28 @@ disregards current point position.
 
 
 <!-- ##### FUNCTION gtk_text_freeze ##### -->
-<para>

-Freezes the #GtkText widget which disallows redrawing of the widget until

-it is thawed.  This is useful if a large number of changes are going to

-made to the text within the widget, reducing the amount of flicker seen

-by the user.

+<para>
+Freezes the #GtkText widget which disallows redrawing of the widget until
+it is thawed.  This is useful if a large number of changes are going to
+made to the text within the widget, reducing the amount of flicker seen
+by the user.
 </para>
 
 @text: the #GtkText widget
 
 
 <!-- ##### FUNCTION gtk_text_thaw ##### -->
-<para>

-Allows the #GtkText widget to be redrawn again by GTK.

+<para>
+Allows the #GtkText widget to be redrawn again by GTK.
 </para>
 
 @text: the #GtkText widget
 
 
 <!-- ##### FUNCTION gtk_text_insert ##### -->
-<para>

-Inserts given text into the #GtkText widget with the given properties as

-outlined below.

+<para>
+Inserts given text into the #GtkText widget with the given properties as
+outlined below.
 </para>
 
 @text: the #GtkText widget
@@ -187,14 +173,14 @@ outlined below.
 @fore: the foreground color to insert with
 @back: the background color to insert with
 @chars: the actual text to be inserted
-@length: the length of the text to be inserted, passing -1 makes it insert

+@length: the length of the text to be inserted, passing -1 makes it insert
 all the text.
 
 
 <!-- ##### FUNCTION gtk_text_backward_delete ##### -->
-<para>

-Deletes from the current point position backward the given number of

-characters.

+<para>
+Deletes from the current point position backward the given number of
+characters.
 </para>
 
 @text: the #GtkText widget
@@ -203,9 +189,9 @@ characters.
 
 
 <!-- ##### FUNCTION gtk_text_forward_delete ##### -->
-<para>

-Deletes from the current point position forward the given number of

-characters.

+<para>
+Deletes from the current point position forward the given number of
+characters.
 </para>
 
 @text: the #GtkText widget
@@ -214,8 +200,8 @@ characters.
 
 
 <!-- ##### MACRO GTK_TEXT_INDEX ##### -->
-<para>

-Returns the character at the given index within the #GtkText widget.

+<para>
+Returns the character at the given index within the #GtkText widget.
 </para>
 
 @t: the #GtkText widget
@@ -232,24 +218,24 @@ Returns the character at the given index within the #GtkText widget.
 @arg2: 
 
 <!-- ##### ARG GtkText:hadjustment ##### -->
-<para>

-Used by the #GtkText widget to keep track of the size of it's horizontal

-text.

+<para>
+Used by the #GtkText widget to keep track of the size of it's horizontal
+text.
 </para>
 
 <!-- ##### ARG GtkText:vadjustment ##### -->
-<para>

-Used by the #GtkText widget to keep track of the size of it's vertical

-text.

+<para>
+Used by the #GtkText widget to keep track of the size of it's vertical
+text.
 </para>
 
 <!-- ##### ARG GtkText:line-wrap ##### -->
-<para>

-Boolean value indicating whether line wrap is enabled or not.

+<para>
+Boolean value indicating whether line wrap is enabled or not.
 </para>
 
 <!-- ##### ARG GtkText:word-wrap ##### -->
-<para>

-Boolean value indicated whether word wrap is enabled or not.

+<para>
+Boolean value indicated whether word wrap is enabled or not.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktree.sgml b/docs/reference/gtk/tmpl/gtktree.sgml
index c61ca2e29..75fcfeec3 100644
--- a/docs/reference/gtk/tmpl/gtktree.sgml
+++ b/docs/reference/gtk/tmpl/gtktree.sgml
@@ -2,7 +2,7 @@
 GtkTree
 
 <!-- ##### SECTION Short_Description ##### -->
-Deprecated tree widget (use #GtkTreeView instead).
+Deprecated tree widget, use #GtkTreeView instead.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -10,7 +10,7 @@ Deprecated tree widget (use #GtkTreeView instead).
 <para>
 #GtkTree is deprecated and unsupported. It is known to be
 buggy. To use it, you must define the symbol %GTK_ENABLE_BROKEN
-prior to including the GTK+ header files. Use #GtkTreeView intead.
+prior to including the GTK+ header files. Use #GtkTreeView instead.
 </para>
 </warning>
 The #GtkTree widget is a container that shows users a list of items, in a tree format complete with branches and leafnodes. Branches can be expanded to show their child items, or collapsed to hide them.
@@ -113,7 +113,7 @@ Adds the #GtkTreeItem in @tree_item to the list of items in @tree at the positio
 
 @tree: A pointer to a #GtkTree.
 @tree_item: A pointer to the #GtkWidget that is to be added to the tree.
-@position: A #gint that indicates the position in the tree, that the tree_item is to be added at.
+@position: A #gint that indicates the position in the tree, that the @tree_item is to be added at.
 
 
 <!-- ##### FUNCTION gtk_tree_remove_items ##### -->
@@ -140,8 +140,8 @@ Removing an item from a #GtkTree dereferences the item, and thus usually destroy
 </para>
 
 @tree: A pointer to a #GtkTree.
-@start: A gint.
-@end: A gint.
+@start: A #gint.
+@end: A #gint.
 
 
 <!-- ##### FUNCTION gtk_tree_select_item ##### -->
@@ -150,7 +150,7 @@ Emits the #select_item signal for the child at position @item, and thus selects
 </para>
 
 @tree: A pointer to a #GtkTree.
-@item: A gint.
+@item: A #gint.
 
 
 <!-- ##### FUNCTION gtk_tree_unselect_item ##### -->
@@ -159,7 +159,7 @@ Emits the #unselect_item for the child at position @item, and thus unselects it.
 </para>
 
 @tree: A pointer to a #GtkTree.
-@item: A gint.
+@item: A #gint.
 
 
 <!-- ##### FUNCTION gtk_tree_select_child ##### -->
@@ -190,7 +190,7 @@ If @child is not a child of @tree, then -1 is returned.
 
 @tree: A pointer to a #GtkTree.
 @child: A pointer to a #GtkWidget.
-@Returns: A gint.
+@Returns: A #gint.
 
 
 <!-- ##### FUNCTION gtk_tree_set_selection_mode ##### -->
@@ -266,7 +266,7 @@ Sets whether or not the connecting lines between branches and children are drawn
 </para>
 
 @tree: A pointer to a #GtkTree.
-@flag: A guint, indicating %TRUE, or %FALSE.
+@flag: A #guint, indicating %TRUE, or %FALSE.
 
 
 <!-- ##### FUNCTION gtk_tree_remove_item ##### -->
diff --git a/docs/reference/gtk/tmpl/gtktreeitem.sgml b/docs/reference/gtk/tmpl/gtktreeitem.sgml
index c04b84ccb..6f404c54f 100644
--- a/docs/reference/gtk/tmpl/gtktreeitem.sgml
+++ b/docs/reference/gtk/tmpl/gtktreeitem.sgml
@@ -2,7 +2,7 @@
 GtkTreeItem
 
 <!-- ##### SECTION Short_Description ##### -->
-
+The widget used for items in a #GtkTree.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -10,7 +10,7 @@ GtkTreeItem
 <para>
 #GtkTree is deprecated and unsupported. It is known to be
 buggy. To use it, you must define the symbol %GTK_ENABLE_BROKEN
-prior to including the GTK+ header files. Use #GtkTreeView intead.
+prior to including the GTK+ header files. Use #GtkTreeView instead.
 </para>
 </warning>
 </para>
diff --git a/docs/reference/gtk/tree_widget.sgml b/docs/reference/gtk/tree_widget.sgml
index 1c64fbbc6..5ff830e86 100644
--- a/docs/reference/gtk/tree_widget.sgml
+++ b/docs/reference/gtk/tree_widget.sgml
@@ -9,7 +9,7 @@
     <refname>Tree and List Widget Overview</refname>
     <refpurpose>Overview of <link
     linkend="GtkTreeModel">GtkTreeModel</link>, <link
-    linkend="GtkTreeView">GtkTreeView</link>, and other assocoiated widgets</refpurpose>
+    linkend="GtkTreeView">GtkTreeView</link>, and other associated widgets</refpurpose>
   </refnamediv>
 
   <refsect1>
diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index 1ffdffc86..fa14ebbd0 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,9 @@
+2001-12-05  Matthias Clasen  <matthiasc@poet.de>
+
+	* gdk-pixbuf.h (gdk_pixbuf_ref, gdk_pixbuf_unref,
+	gdk_pixbuf_animation_ref, gdk_pixbuf_animation_unref):
+	Deprecate. (#66208)
+
 Tue Dec  4 11:45:45 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* io-xpm.c (pixbuf_create_from_xpm): Fill in color 
diff --git a/gdk-pixbuf/gdk-pixbuf.h b/gdk-pixbuf/gdk-pixbuf.h
index f63ce7731..7c616f8dd 100644
--- a/gdk-pixbuf/gdk-pixbuf.h
+++ b/gdk-pixbuf/gdk-pixbuf.h
@@ -96,8 +96,10 @@ GType gdk_pixbuf_get_type (void) G_GNUC_CONST;
 
 /* Reference counting */
 
+#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
 GdkPixbuf *gdk_pixbuf_ref      (GdkPixbuf *pixbuf);
 void       gdk_pixbuf_unref    (GdkPixbuf *pixbuf);
+#endif
 
 /* GdkPixbuf accessors */
 
@@ -262,8 +264,10 @@ GType               gdk_pixbuf_animation_get_type        (void) G_GNUC_CONST;
 GdkPixbufAnimation *gdk_pixbuf_animation_new_from_file   (const char         *filename,
                                                           GError            **error);
 
+#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
 GdkPixbufAnimation *gdk_pixbuf_animation_ref             (GdkPixbufAnimation *animation);
 void                gdk_pixbuf_animation_unref           (GdkPixbufAnimation *animation);
+#endif
 
 int                 gdk_pixbuf_animation_get_width       (GdkPixbufAnimation *animation);
 int                 gdk_pixbuf_animation_get_height      (GdkPixbufAnimation *animation);
diff --git a/gdk/gdkimage.h b/gdk/gdkimage.h
index 3862b0fa6..3bb79b26f 100644
--- a/gdk/gdkimage.h
+++ b/gdk/gdkimage.h
@@ -66,13 +66,13 @@ GdkImage*  gdk_image_new       (GdkImageType  type,
 				gint	      width,
 				gint	      height);
 
+#ifndef GDK_DISABLE_DEPRECATED
 GdkImage*  gdk_image_get       (GdkDrawable  *drawable,
 				gint	      x,
 				gint	      y,
 				gint	      width,
 				gint	      height);
 
-#ifndef GDK_DISABLE_DEPRECATED
 GdkImage * gdk_image_ref       (GdkImage     *image);
 void       gdk_image_unref     (GdkImage     *image);
 #endif
diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h
index 9383c7a25..4cd57c831 100644
--- a/gdk/gdkwindow.h
+++ b/gdk/gdkwindow.h
@@ -435,9 +435,13 @@ void	      gdk_window_get_position	 (GdkWindow	  *window,
 gint	      gdk_window_get_origin	 (GdkWindow	  *window,
 					  gint		  *x,
 					  gint		  *y);
+
+#ifndef GDK_DISABLE_DEPRECATED
 gboolean      gdk_window_get_deskrelative_origin (GdkWindow	  *window,
 					  gint		  *x,
 					  gint		  *y);
+#endif
+
 void	      gdk_window_get_root_origin (GdkWindow	  *window,
 					  gint		  *x,
 					  gint		  *y);
diff --git a/gtk/gtkbbox.c b/gtk/gtkbbox.c
index a1d7ec493..2c4c4307a 100644
--- a/gtk/gtkbbox.c
+++ b/gtk/gtkbbox.c
@@ -335,9 +335,9 @@ gtk_button_box_get_layout (GtkButtonBox *widget)
  * is %GTK_BUTTONBOX_START, %GTK_BUTTONBOX_SPREAD or
  * %GTK_BUTTONBOX_EDGE, and before the the other children if the style
  * is %GTK_BUTTONBOX_END. For horizontal button boxes, the definition
- * of before/after depends on direction of the widget. (See
- * gtk_widget_set_direction()) If the style is %GTK_BUTTONBOX_START,
- * or %GTK_BUTTONBOX_START, then the secondary children are aligned at
+ * of before/after depends on direction of the widget (see
+ * gtk_widget_set_direction()). If the style is %GTK_BUTTONBOX_START
+ * or %GTK_BUTTONBOX_END, then the secondary children are aligned at
  * the other end of the button box from the main children. For the
  * other styles, they appear immediately next to the main children.
  **/
diff --git a/gtk/gtkcolorsel.c b/gtk/gtkcolorsel.c
index c5b9b644f..891f7ce6c 100644
--- a/gtk/gtkcolorsel.c
+++ b/gtk/gtkcolorsel.c
@@ -2021,8 +2021,6 @@ gtk_color_selection_set_update_policy (GtkColorSelection *colorsel,
 				       GtkUpdateType      policy)
 {
   g_return_if_fail (GTK_IS_COLOR_SELECTION (colorsel));
-  /* */
-  g_warning (G_STRLOC ": This function is deprecated.");
 }
 
 /**
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 8a2691960..b4d128b1b 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -2085,7 +2085,7 @@ gtk_container_set_focus_hadjustment (GtkContainer  *container,
  * Retrieves the horizontal focus adjustment for the container. See
  * gtk_container_set_focus_hadjustment ().
  *
- * Return value: the horizontal focus adjustment, or %NULL if none
+ * Return value: the horizontal focus adjustment, or %NULL if
  *   none has been set.
  **/
 GtkAdjustment *
@@ -2211,9 +2211,9 @@ gtk_container_unmap (GtkWidget *widget)
  * @event: a expose event sent to container
  *
  *  When a container receives an expose event, it must send synthetic
- * expose events to all children that don't have their own GdkWindows.
+ * expose events to all children that don't have their own #GdkWindows.
  * This function provides a convenient way of doing this. A container,
- * when it receives an expose event, gtk_container_propagate_expose() 
+ * when it receives an expose event, calls gtk_container_propagate_expose() 
  * once for each child, passing in the event the container received.
  *
  * gtk_container_propagate_expose() takes care of deciding whether
@@ -2221,7 +2221,7 @@ gtk_container_unmap (GtkWidget *widget)
  * the event's area with the child area, and sending the event.
  * 
  * In most cases, a container can simply either simply inherit the
- * ::expose implementation from GtkContainer, or, do some drawing 
+ * ::expose implementation from #GtkContainer, or, do some drawing 
  * and then chain to the ::expose implementation from GtkContainer.
  **/
 void
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index d82c9cd18..b85fc52e1 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -600,7 +600,8 @@ gtk_label_init (GtkLabel *label)
  * gtk_label_new:
  * @str: The text of the label
  *
- * Creates a new #GtkLabel, containing the text in @str.
+ * Creates a new label with the given text inside it. You can
+ * pass %NULL to get an empty label widget.
  *
  * Return value: the new #GtkLabel
  **/
@@ -896,9 +897,10 @@ gtk_label_recalculate (GtkLabel *label)
 /**
  * gtk_label_set_text:
  * @label: a #GtkLabel
- * @str: a string
+ * @str: The text you want to set.
  *
- * Sets the text of the label to @str.
+ * Sets the text within the #GtkLabel widget.  It overwrites any text that
+ * was there before.  
  *
  * This will also clear any previously set mnemonic accelerators.
  **/
@@ -1184,7 +1186,8 @@ gtk_label_set_pattern (GtkLabel	   *label,
  * @jtype: a #GtkJustification
  *
  * Sets the alignment of the lines in the text of the label relative to
- * each other.
+ * each other.  %GTK_JUSTIFY_CENTER is the default value when the
+ * widget is first created with gtk_label_new().
  **/
 void
 gtk_label_set_justify (GtkLabel        *label,
@@ -1226,8 +1229,10 @@ gtk_label_get_justify (GtkLabel *label)
  * @label: a #GtkLabel
  * @wrap: the setting
  *
- * If true, the lines will be wrapped if the text becomes too wide.
- */
+ * Toggles line wrapping within the #GtkLabel widget.  %TRUE makes it break
+ * lines if text exceeds the widget's size.  %FALSE lets the text get cut off
+ * by the edge of the widget if it exceeds the widget size.
+ **/
 void
 gtk_label_set_line_wrap (GtkLabel *label,
 			 gboolean  wrap)
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 73cb020f9..4f7f8134b 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -261,9 +261,9 @@ gtk_list_store_init (GtkListStore *list_store)
  * @Varargs: all #GType types for the columns, from first to last
  *
  * Creates a new list store as with @n_columns columns each of the types passed
- * in.  As an example, gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
- * GDK_TYPE_PIXBUF); will create a new GtkListStore with three columns, of type
- * int, string and GDkPixbuf respectively.
+ * in.  As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
+ * GDK_TYPE_PIXBUF);</literal> will create a new #GtkListStore with three columns, of type
+ * int, string and #GdkPixbuf respectively.
  *
  * Return value: a new #GtkListStore
  **/
@@ -306,7 +306,7 @@ gtk_list_store_new (gint n_columns,
  * @n_columns: number of columns in the list store
  * @types: an array of #GType types for the columns, from first to last
  *
- * Non vararg creation function.  Used primarily by language bindings.
+ * Non-vararg creation function.  Used primarily by language bindings.
  *
  * Return value: a new #GtkListStore
  **/
@@ -341,11 +341,11 @@ gtk_list_store_newv (gint   n_columns,
  * gtk_list_store_set_column_types:
  * @list_store: A #GtkListStore
  * @n_columns: Number of columns for the list store
- * @types: An array length n of @GTypes
+ * @types: An array length n of #GTypes
  * 
- * This function is meant primarily for GObjects that inherit from GtkListStore,
- * and should only be used when constructing a new @GtkListStore.  It will not
- * function after a row has been added, or a method on the @GtkTreeModel
+ * This function is meant primarily for #GObjects that inherit from #GtkListStore,
+ * and should only be used when constructing a new #GtkListStore.  It will not
+ * function after a row has been added, or a method on the #GtkTreeModel
  * interface is called.
  **/
 void
@@ -854,8 +854,8 @@ gtk_list_store_set_valist (GtkListStore *list_store,
  * The variable argument list should contain integer column numbers,
  * each column number followed by the value to be set.
  * The list is terminated by a -1. For example, to set column 0 with type
- * %G_TYPE_STRING to "Foo", you would write gtk_list_store_set (store, iter,
- * 0, "Foo", -1).
+ * %G_TYPE_STRING to "Foo", you would write <literal>gtk_list_store_set (store, iter,
+ * 0, "Foo", -1)</literal>.
  **/
 void
 gtk_list_store_set (GtkListStore *list_store,
@@ -1205,7 +1205,7 @@ gtk_list_store_insert_after (GtkListStore *list_store,
  * @list_store: A #GtkListStore
  * @iter: An unset #GtkTreeIter to set to the prepend row
  *
- * Prepend a new row to @list_store. @iter will be changed to point to this new
+ * Prepends a new row to @list_store. @iter will be changed to point to this new
  * row. The row will be empty after this function is called. To fill in
  * values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
  *
@@ -1287,6 +1287,13 @@ gtk_list_store_append (GtkListStore *list_store,
   gtk_tree_path_free (path);
 }
 
+/**
+ * gtk_list_store_clear:
+ * @list_store: a #GtkListStore.
+ *
+ * Removes all rows from the list store.  
+ *
+ **/
 void
 gtk_list_store_clear (GtkListStore *list_store)
 {
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index dfdd6fea2..9e9c40dd6 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -652,23 +652,22 @@ gtk_style_new (void)
   return style;
 }
 
-/*************************************************************
+/**
  * gtk_style_attach:
- *     Attach a style to a window; this process allocates the
- *     colors and creates the GC's for the style - it specializes
- *     it to a particular visual and colormap. The process
- *     may involve the creation of a new style if the style
- *     has already been attached to a window with a different
- *     style and colormap.
- *   arguments:
- *     style:
- *     window: 
- *   results:
- *     Either the style parameter, or a newly created style.
- *     If the style is newly created, the style parameter
- *     will be dereferenced, and the new style will have
- *     a reference count belonging to the caller.
+ * @style: a #GtkStyle.
+ * @window: a #GtkWindow.
+ * @returns: Either @style, or a newly-created #GtkStyle.
+ *   If the style is newly created, the style parameter
+ *   will be dereferenced, and the new style will have
+ *   a reference count belonging to the caller.
  *
+ * Attaches a style to a window; this process allocates the
+ * colors and creates the GC's for the style - it specializes
+ * it to a particular visual and colormap. The process may 
+ * involve the creation of a new style if the style has already 
+ * been attached to a window with a different style and colormap.
+ **/
+ /*
  * FIXME: The sequence - 
  *    create a style => s1
  *    attach s1 to v1, c1 => s1
@@ -683,8 +682,7 @@ gtk_style_new (void)
  * passes through the linked list when attaching (one to check for 
  * matching styles, one to look for empty unattached styles - but 
  * it will almost never be longer than 2 elements.
- *************************************************************/
-
+ */
 GtkStyle*
 gtk_style_attach (GtkStyle  *style,
                   GdkWindow *window)