Fix malformed doc comments

Most of these are forgotten :'s and similar details
which gtk-doc now warns about.

36 files changed, 79 insertions, 90 deletions

diff --git a/gtk/deprecated/gtkcolorsel.c b/gtk/deprecated/gtkcolorsel.c
index b9435f1933..ae77a6684f 100644
--- a/gtk/deprecated/gtkcolorsel.c
+++ b/gtk/deprecated/gtkcolorsel.c
@@ -333,7 +333,7 @@ gtk_color_selection_class_init (GtkColorSelectionClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkColorSelection:current-color
+   * GtkColorSelection:current-color:
    *
    * The current GdkColor color.
    *
@@ -355,7 +355,7 @@ gtk_color_selection_class_init (GtkColorSelectionClass *klass)
                                                       GTK_PARAM_READWRITE));
 
   /**
-   * GtkColorSelection:current-rgba
+   * GtkColorSelection:current-rgba:
    *
    * The current RGBA color.
    *
diff --git a/gtk/gtkbbox.c b/gtk/gtkbbox.c
index 3077f1735a..8385e2dd2e 100644
--- a/gtk/gtkbbox.c
+++ b/gtk/gtkbbox.c
@@ -391,7 +391,7 @@ gtk_button_box_get_child_secondary (GtkButtonBox *widget,
 }
 
 /**
- * gtk_button_box_set_child_secondary
+ * gtk_button_box_set_child_secondary:
  * @widget: a #GtkButtonBox
  * @child: a child of @widget
  * @is_secondary: if %TRUE, the @child appears in a secondary group of the
diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 8f548e4d0b..89d4142881 100644
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -610,7 +610,7 @@ gtk_calendar_class_init (GtkCalendarClass *class)
 
 
   /**
-   * GtkCalendar:inner-border
+   * GtkCalendar:inner-border:
    *
    * The spacing around the day/week headers and main area.
    */
@@ -622,7 +622,7 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                                                              GTK_PARAM_READABLE));
 
   /**
-   * GtkCalndar:vertical-separation
+   * GtkCalndar:vertical-separation:
    *
    * Separation between day headers and main area.
    */
@@ -634,7 +634,7 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                                                              GTK_PARAM_READABLE));
 
   /**
-   * GtkCalendar:horizontal-separation
+   * GtkCalendar:horizontal-separation:
    *
    * Separation between week headers and main area.
    */
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 6efb490c5c..eb651b87ab 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -2335,7 +2335,7 @@ gtk_cell_area_attribute_disconnect (GtkCellArea        *area,
 }
 
 /**
- * gtk_cell_area_apply_attributes
+ * gtk_cell_area_apply_attributes:
  * @area: a #GtkCellArea
  * @tree_model: the #GtkTreeModel to pull values from
  * @iter: the #GtkTreeIter in @tree_model to apply values for
diff --git a/gtk/gtkcellrenderertext.c b/gtk/gtkcellrenderertext.c
index e4b5f7248b..ca88fc78c0 100644
--- a/gtk/gtkcellrenderertext.c
+++ b/gtk/gtkcellrenderertext.c
@@ -691,7 +691,7 @@ gtk_cell_renderer_text_class_init (GtkCellRendererTextClass *class)
                 P_("Whether this tag affects the alignment mode"));
 
   /**
-   * GtkCellRendererText::edited
+   * GtkCellRendererText::edited:
    * @renderer: the object which received the signal
    * @path: the path identifying the edited cell
    * @new_text: the new text
diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c
index cee08d548c..94169f917d 100644
--- a/gtk/gtkcellview.c
+++ b/gtk/gtkcellview.c
@@ -192,7 +192,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
                                                         GTK_PARAM_WRITABLE));
 
   /**
-   * GtkCellView:background-gdk
+   * GtkCellView:background-gdk:
    *
    * The background color as a #GdkColor
    *
@@ -206,7 +206,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
                                                       GDK_TYPE_COLOR,
                                                       GTK_PARAM_READWRITE | G_PARAM_DEPRECATED));
   /**
-   * GtkCellView:background-rgba
+   * GtkCellView:background-rgba:
    *
    * The background color as a #GdkRGBA
    *
@@ -221,7 +221,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
                                                       GTK_PARAM_READWRITE));
 
   /**
-   * GtkCellView:model
+   * GtkCellView:model:
    *
    * The model for cell view
    *
@@ -237,7 +237,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
 
 
   /**
-   * GtkCellView:cell-area
+   * GtkCellView:cell-area:
    *
    * The #GtkCellArea rendering cells
    *
@@ -255,7 +255,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
 							 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
   /**
-   * GtkCellView:cell-area-context
+   * GtkCellView:cell-area-context:
    *
    * The #GtkCellAreaContext used to compute the geometry of the cell view.
    *
@@ -280,7 +280,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
 							 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
   /**
-   * GtkCellView:draw-sensitive
+   * GtkCellView:draw-sensitive:
    *
    * Whether all cells should be draw as sensitive for this view regardless
    * of the actual cell properties (used to make menus with submenus appear
@@ -298,7 +298,7 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
 							  GTK_PARAM_READWRITE));
 
   /**
-   * GtkCellView:fit-model
+   * GtkCellView:fit-model:
    *
    * Whether the view should request enough space to always fit
    * the size of every row in the model (used by the combo box to
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index 02c67c14da..368b413fac 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -1816,7 +1816,7 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
 }
 
 /**
- * gtk_clipboard_wait_for_targets
+ * gtk_clipboard_wait_for_targets:
  * @clipboard: a #GtkClipboard
  * @targets: (out) (array length=n_targets) (transfer container): location
  *           to store an array of targets. The result stored here must
@@ -1824,9 +1824,9 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
  * @n_targets: location to store number of items in @targets.
  *
  * Returns a list of targets that are present on the clipboard, or %NULL
- * if there aren't any targets available. The returned list must be 
+ * if there aren't any targets available. The returned list must be
  * freed with g_free().
- * This function waits for the data to be received using the main 
+ * This function waits for the data to be received using the main
  * loop, so events, timeouts, etc, may be dispatched during the wait.
  *
  * Return value: %TRUE if any targets are present on the clipboard,
diff --git a/gtk/gtkcsssection.c b/gtk/gtkcsssection.c
index dd4cc021f7..007a308b9b 100644
--- a/gtk/gtkcsssection.c
+++ b/gtk/gtkcsssection.c
@@ -192,11 +192,11 @@ gtk_css_section_get_parent (const GtkCssSection *section)
  * @section: the section
  *
  * Gets the file that @section was parsed from. If no such file exists,
- * for example because the CSS was loaded via 
+ * for example because the CSS was loaded via
  * @gtk_css_provider_load_from_data(), then %NULL is returned.
  *
- * Returns: the #GFile that @section was parsed from or %NULL if
- *   @section was parsed from other data.
+ * Returns: (transfer none): the #GFile that @section was parsed from
+ *     or %NULL if @section was parsed from other data
  *
  * Since: 3.2
  **/
diff --git a/gtk/gtkcsssection.h b/gtk/gtkcsssection.h
index e35ffc8a90..7901a43d03 100644
--- a/gtk/gtkcsssection.h
+++ b/gtk/gtkcsssection.h
@@ -26,7 +26,7 @@ G_BEGIN_DECLS
 #define GTK_TYPE_CSS_SECTION         (gtk_css_section_get_type ())
 
 /**
- * GtkCssSection:
+ * GtkCssSectionType:
  * @GTK_CSS_SECTION_DOCUMENT: The section describes a complete document.
  *   This section time is the only one where gtk_css_section_get_parent()
  *   might return %NULL.
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index f8ac85f3dc..28bf32b5e4 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -942,7 +942,7 @@ gtk_entry_class_init (GtkEntryClass *class)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkEntry:caps-lock-warning
+   * GtkEntry:caps-lock-warning:
    *
    * Whether password entries will show a warning when Caps Lock is on.
    *
diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index cb4aad68a3..ef2dc9e060 100644
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -1708,7 +1708,7 @@ gtk_entry_completion_cursor_on_match (GtkEntryCompletion *completion,
  * Note that a text column must have been set for this function to work,
  * see gtk_entry_completion_set_text_column() for details. 
  *
- * Returns: (transfer: full): The common prefix all rows starting with @key
+ * Returns: (transfer full): The common prefix all rows starting with @key
  *   or %NULL if no row matches @key.
  *
  * Since: 3.4
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index dc444dcba5..a24ac26f77 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -90,7 +90,7 @@ typedef enum
 } GtkArrowPlacement;
 
 /**
- * GtkArrowType
+ * GtkArrowType:
  * @GTK_ARROW_UP: Represents an upward pointing arrow.
  * @GTK_ARROW_DOWN: Represents a downward pointing arrow.
  * @GTK_ARROW_LEFT: Represents a left pointing arrow.
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index b5f992c069..df794e2ae1 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -554,7 +554,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
   GType iface_type = G_TYPE_FROM_INTERFACE (iface);
 
   /**
-   * GtkFileChooser::current-folder-changed
+   * GtkFileChooser::current-folder-changed:
    * @chooser: the object which received the signal.
    *
    * This signal is emitted when the current folder in a #GtkFileChooser
@@ -580,7 +580,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
 		G_TYPE_NONE, 0);
 
   /**
-   * GtkFileChooser::selection-changed
+   * GtkFileChooser::selection-changed:
    * @chooser: the object which received the signal.
    *
    * This signal is emitted when there is a change in the set of selected files
@@ -607,7 +607,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
 		G_TYPE_NONE, 0);
 
   /**
-   * GtkFileChooser::update-preview
+   * GtkFileChooser::update-preview:
    * @chooser: the object which received the signal.
    *
    * This signal is emitted when the preview in a file chooser should be
@@ -641,7 +641,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
 		G_TYPE_NONE, 0);
 
   /**
-   * GtkFileChooser::file-activated
+   * GtkFileChooser::file-activated:
    * @chooser: the object which received the signal.
    *
    * This signal is emitted when the user "activates" a file in the file
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index d068847e76..5b060960c0 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -20,6 +20,7 @@
  * SECTION:gtkfilefilter
  * @Short_description: A filter for selecting a file subset
  * @Title: GtkFileFilter
+ * @see_also: #GtkFileChooser
  *
  * A GtkFileFilter can be used to restrict the files being shown in a
  * #GtkFileChooser. Files can be filtered based on their name (with
@@ -63,8 +64,6 @@
  * </example>
  * </para>
  * </refsect2>
- *
- * @see_also: #GtkFileChooser
  */
 
 #include "config.h"
diff --git a/gtk/gtkfilefilter.h b/gtk/gtkfilefilter.h
index babc6b6318..b7c6c68500 100644
--- a/gtk/gtkfilefilter.h
+++ b/gtk/gtkfilefilter.h
@@ -61,7 +61,7 @@ typedef enum {
  * The type of function that is used with custom filters, see
  * gtk_file_filter_add_custom().
  *
- * @Returns: %TRUE if the file should be displayed
+ * Returns: %TRUE if the file should be displayed
  */
 typedef gboolean (*GtkFileFilterFunc) (const GtkFileFilterInfo *filter_info,
 				       gpointer                 data);
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index c0adfa01c6..c95b46c757 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -2146,7 +2146,7 @@ gtk_icon_source_set_filename (GtkIconSource *source,
 }
 
 /**
- * gtk_icon_source_set_icon_name
+ * gtk_icon_source_set_icon_name:
  * @source: a #GtkIconSource
  * @icon_name: (allow-none): name of icon to use
  *
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index e55d72eeb7..2b4d1d4570 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -429,7 +429,7 @@ gtk_icon_theme_class_init (GtkIconThemeClass *klass)
   gobject_class->finalize = gtk_icon_theme_finalize;
 
 /**
- * GtkIconTheme::changed
+ * GtkIconTheme::changed:
  * @icon_theme: the icon theme
  * 
  * Emitted when the current icon theme is switched or GTK+ detects
diff --git a/gtk/gtklinkbutton.c b/gtk/gtklinkbutton.c
index 505fb0095b..15a52f6a85 100644
--- a/gtk/gtklinkbutton.c
+++ b/gtk/gtklinkbutton.c
@@ -163,9 +163,9 @@ gtk_link_button_class_init (GtkLinkButtonClass *klass)
   klass->activate_link = gtk_link_button_activate_link;
 
   /**
-   * GtkLinkButton:uri
-   * 
-   * The URI bound to this button. 
+   * GtkLinkButton:uri:
+   *
+   * The URI bound to this button.
    *
    * Since: 2.10
    */
@@ -177,8 +177,8 @@ gtk_link_button_class_init (GtkLinkButtonClass *klass)
   				   			NULL,
   				   			G_PARAM_READWRITE));
   /**
-   * GtkLinkButton:visited
-   * 
+   * GtkLinkButton:visited:
+   *
    * The 'visited' state of this button. A visited link is drawn in a
    * different color.
    *
diff --git a/gtk/gtklockbutton.c b/gtk/gtklockbutton.c
index 51dc2f4d5c..70d2a4d689 100644
--- a/gtk/gtklockbutton.c
+++ b/gtk/gtklockbutton.c
@@ -504,7 +504,7 @@ gtk_lock_button_new (GPermission *permission)
  *
  * Obtains the #GPermission object that controls @button.
  *
- * Returns: the #GPermission of @button
+ * Returns: (transfer none): the #GPermission of @button
  *
  * Since: 3.2
  */
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 88be4e3b0b..f52d110c0b 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -753,7 +753,7 @@ gtk_menu_class_init (GtkMenuClass *class)
                                                                GTK_PARAM_READWRITE));
 
  /**
-  * GtkMenu:arrow-scaling
+  * GtkMenu:arrow-scaling:
   *
   * Arbitrary constant to scale down the size of the scroll arrow.
   *
@@ -2000,7 +2000,7 @@ gtk_menu_real_can_activate_accel (GtkWidget *widget,
 }
 
 /**
- * gtk_menu_set_accel_path
+ * gtk_menu_set_accel_path:
  * @menu:       a valid #GtkMenu
  * @accel_path: (allow-none): a valid accelerator path
  *
@@ -2043,7 +2043,7 @@ gtk_menu_set_accel_path (GtkMenu     *menu,
 }
 
 /**
- * gtk_menu_get_accel_path
+ * gtk_menu_get_accel_path:
  * @menu: a valid #GtkMenu
  *
  * Retrieves the accelerator path set on the menu.
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 5a7b166748..388c2a5038 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -2356,7 +2356,7 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
 }
 
 /**
- * gtk_menu_item_set_accel_path
+ * gtk_menu_item_set_accel_path:
  * @menu_item:  a valid #GtkMenuItem
  * @accel_path: (allow-none): accelerator path, corresponding to this menu
  *     item's functionality, or %NULL to unset the current path.
@@ -2416,7 +2416,7 @@ gtk_menu_item_set_accel_path (GtkMenuItem *menu_item,
 }
 
 /**
- * gtk_menu_item_get_accel_path
+ * gtk_menu_item_get_accel_path:
  * @menu_item:  a valid #GtkMenuItem
  *
  * Retrieve the accelerator path that was previously set on @menu_item.
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 8e13eff991..8ead95243f 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -291,7 +291,7 @@ gtk_message_dialog_class_init (GtkMessageDialogClass *class)
                                                         GTK_PARAM_READWRITE));
 
   /**
-   * GtkMessageDialog:message-area
+   * GtkMessageDialog:message-area:
    *
    * The #GtkVBox that corresponds to the message area of this dialog.  See
    * gtk_message_dialog_get_message_area() for a detailed description of this
diff --git a/gtk/gtkplug.c b/gtk/gtkplug.c
index d584b7ff89..048ef2915e 100644
--- a/gtk/gtkplug.c
+++ b/gtk/gtkplug.c
@@ -247,7 +247,6 @@ gtk_plug_init (GtkPlug *plug)
 
 /**
  * gtk_plug_handle_modality_on:
- *
  * @plug: a #GtkPlug
  *
  * Called from the GtkPlug backend when the corresponding socket has
@@ -271,7 +270,6 @@ gtk_plug_handle_modality_on (GtkPlug *plug)
 
 /**
  * gtk_plug_handle_modality_off:
- *
  * @plug: a #GtkPlug
  *
  * Called from the GtkPlug backend when the corresponding socket has
@@ -719,7 +717,6 @@ xembed_set_info (GdkWindow     *window,
 
 /**
  * gtk_plug_focus_first_last:
- *
  * @plug: a #GtkPlug
  * @direction: a direction
  *
diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c
index 1ff64e292a..bbaa4c6135 100644
--- a/gtk/gtkrecentchooser.c
+++ b/gtk/gtkrecentchooser.c
@@ -78,7 +78,7 @@ gtk_recent_chooser_default_init (GtkRecentChooserInterface *iface)
   quark_gtk_use_action_appearance = g_quark_from_static_string (gtk_use_action_appearance_key);
   
   /**
-   * GtkRecentChooser::selection-changed
+   * GtkRecentChooser::selection-changed:
    * @chooser: the object which received the signal
    *
    * This signal is emitted when there is a change in the set of
@@ -98,7 +98,7 @@ gtk_recent_chooser_default_init (GtkRecentChooserInterface *iface)
                   G_TYPE_NONE, 0);
    
   /**
-   * GtkRecentChooser::item-activated
+   * GtkRecentChooser::item-activated:
    * @chooser: the object which received the signal
    *
    * This signal is emitted when the user "activates" a recent item
diff --git a/gtk/gtkrecentchoosermenu.c b/gtk/gtkrecentchoosermenu.c
index f3d73ffcfa..25dc025be4 100644
--- a/gtk/gtkrecentchoosermenu.c
+++ b/gtk/gtkrecentchoosermenu.c
@@ -231,7 +231,7 @@ gtk_recent_chooser_menu_class_init (GtkRecentChooserMenuClass *klass)
   _gtk_recent_chooser_install_properties (gobject_class);
 
   /**
-   * GtkRecentChooserMenu:show-numbers
+   * GtkRecentChooserMenu:show-numbers:
    *
    * Whether the first ten items in the menu should be prepended by
    * a number acting as a unique mnemonic.
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index d5fac3dc64..9d20011cce 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -280,7 +280,7 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
   gobject_class->finalize = gtk_recent_manager_finalize;
   
   /**
-   * GtkRecentManager:filename
+   * GtkRecentManager:filename:
    *
    * The full path to the file to be used to store and read the recently
    * used resources list
@@ -296,7 +296,7 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
 							(G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE)));
 
   /**
-   * GtkRecentManager:size
+   * GtkRecentManager:size:
    * 
    * The size of the recently used resources list.
    *
@@ -313,7 +313,7 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
 						     G_PARAM_READABLE));
   
   /**
-   * GtkRecentManager::changed
+   * GtkRecentManager::changed:
    * @recent_manager: the recent manager
    *
    * Emitted when the current recently used resources manager changes its
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index 4aac2e032e..6a0202c9d7 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -439,7 +439,6 @@ gtk_socket_realize (GtkWidget *widget)
 
 /**
  * gtk_socket_end_embedding:
- *
  * @socket: a #GtkSocket
  *
  * Called to end the embedding of a plug in the socket.
@@ -731,7 +730,6 @@ find_accel_key (GtkAccelKey *key,
 
 /**
  * gtk_socket_add_grabbed_key:
- *
  * @socket: a #GtkSocket
  * @keyval: a key
  * @modifiers: modifiers for the key
@@ -921,7 +919,6 @@ gtk_socket_notify (GObject    *object,
 
 /**
  * gtk_socket_claim_focus:
- *
  * @socket: a #GtkSocket
  * @send_event: huh?
  *
@@ -1008,11 +1005,10 @@ gtk_socket_forall (GtkContainer *container,
 
 /**
  * gtk_socket_add_window:
- *
  * @socket: a #GtkSocket
  * @xid: the native identifier for a window
  * @need_reparent: whether the socket's plug's window needs to be
- *		   reparented to the socket
+ *                 reparented to the socket
  *
  * Adds a window to a GtkSocket.
  */
@@ -1145,7 +1141,6 @@ gtk_socket_add_window (GtkSocket       *socket,
 
 /**
  * gtk_socket_handle_map_request:
- *
  * @socket: a #GtkSocket
  *
  * Called from the GtkSocket backend when the plug has been mapped.
@@ -1183,7 +1178,6 @@ gtk_socket_unmap_notify (GtkSocket *socket)
 
 /**
  * gtk_socket_advance_toplevel_focus:
- *
  * @socket: a #GtkSocket
  * @direction: a direction
  *
diff --git a/gtk/gtkstyleprovider.h b/gtk/gtkstyleprovider.h
index 9573dc291b..62b3aeb9cd 100644
--- a/gtk/gtkstyleprovider.h
+++ b/gtk/gtkstyleprovider.h
@@ -85,7 +85,7 @@ typedef struct _GtkStyleProviderIface GtkStyleProviderIface;
 typedef struct _GtkStyleProvider GtkStyleProvider; /* dummy typedef */
 
 /**
- * GtkStyleProviderIface
+ * GtkStyleProviderIface:
  * @get_style: Gets a set of style information that applies to a widget path.
  * @get_style_property: Gets the value of a widget style property that applies to a widget path.
  * @get_icon_factory: Gets the icon factory that applies to a widget path.
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 1f04668ab5..2b41c34cfb 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -2472,7 +2472,7 @@ gtk_text_iter_forward_text_chars  (GtkTextIter *iter,
 }
 
 /**
- * gtk_text_iter_forward_text_chars:
+ * gtk_text_iter_backward_text_chars:
  * @iter: a #GtkTextIter
  * @count: number of chars to move
  *
diff --git a/gtk/gtkthemingengine.h b/gtk/gtkthemingengine.h
index aa7e05388c..0c3339ebf8 100644
--- a/gtk/gtkthemingengine.h
+++ b/gtk/gtkthemingengine.h
@@ -50,7 +50,7 @@ struct _GtkThemingEngine
 };
 
 /**
- * GtkThemingEngineClass
+ * GtkThemingEngineClass:
  * @parent_class: The parent class.
  * @render_line: Renders a line between two points.
  * @render_background: Renders the background area of a widget region.
diff --git a/gtk/gtktoolbutton.c b/gtk/gtktoolbutton.c
index 0aca80ea77..1999458d76 100644
--- a/gtk/gtktoolbutton.c
+++ b/gtk/gtktoolbutton.c
@@ -1226,7 +1226,7 @@ gtk_tool_button_get_stock_id (GtkToolButton *button)
 }
 
 /**
- * gtk_tool_button_set_icon_name
+ * gtk_tool_button_set_icon_name:
  * @button: a #GtkToolButton
  * @icon_name: (allow-none): the name of the themed icon
  *
@@ -1257,15 +1257,15 @@ gtk_tool_button_set_icon_name (GtkToolButton *button,
 }
 
 /**
- * gtk_tool_button_get_icon_name
+ * gtk_tool_button_get_icon_name:
  * @button: a #GtkToolButton
- * 
+ *
  * Returns the name of the themed icon for the tool button,
  * see gtk_tool_button_set_icon_name().
  *
  * Returns: the icon name or %NULL if the tool button has
  * no themed icon
- * 
+ *
  * Since: 2.8
  **/
 const gchar*
diff --git a/gtk/gtktoolshell.c b/gtk/gtktoolshell.c
index 765a02d168..7ebf18c648 100644
--- a/gtk/gtktoolshell.c
+++ b/gtk/gtktoolshell.c
@@ -28,11 +28,10 @@
  * SECTION:gtktoolshell
  * @Short_description: Interface for containers containing GtkToolItem widgets
  * @Title: GtkToolShell
+ * @see_also: #GtkToolbar, #GtkToolItem
  *
  * The #GtkToolShell interface allows container widgets to provide additional
  * information when embedding #GtkToolItem widgets.
- *
- * @see_also: #GtkToolbar, #GtkToolItem
  */
 
 /**
@@ -219,7 +218,7 @@ gtk_tool_shell_get_text_alignment (GtkToolShell *shell)
 }
 
 /**
- * gtk_tool_shell_get_ellipsize_mode
+ * gtk_tool_shell_get_ellipsize_mode:
  * @shell: a #GtkToolShell
  *
  * Retrieves the current ellipsize mode for the tool shell. Tool items must not
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 01194b1068..73cd0ae157 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -11852,7 +11852,7 @@ gtk_tree_view_get_headers_clickable (GtkTreeView *tree_view)
 }
 
 /**
- * gtk_tree_view_set_rules_hint
+ * gtk_tree_view_set_rules_hint:
  * @tree_view: a #GtkTreeView
  * @setting: %TRUE if the tree requires reading across rows
  *
@@ -11888,7 +11888,7 @@ gtk_tree_view_set_rules_hint (GtkTreeView  *tree_view,
 }
 
 /**
- * gtk_tree_view_get_rules_hint
+ * gtk_tree_view_get_rules_hint:
  * @tree_view: a #GtkTreeView
  *
  * Gets the setting set by gtk_tree_view_set_rules_hint().
diff --git a/gtk/gtkvolumebutton.c b/gtk/gtkvolumebutton.c
index 823d1decbf..ceb64721f5 100644
--- a/gtk/gtkvolumebutton.c
+++ b/gtk/gtkvolumebutton.c
@@ -204,7 +204,7 @@ gtk_volume_button_init (GtkVolumeButton *button)
 }
 
 /**
- * gtk_volume_button_new
+ * gtk_volume_button_new:
  *
  * Creates a #GtkVolumeButton, with a range between 0.0 and 1.0, with
  * a stepping of 0.02. Volume values can be obtained and modified using
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 66f6674dac..aea3574aee 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1184,7 +1184,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
 							GTK_PARAM_READABLE));
 
   /**
-   * GtkWidget:double-buffered
+   * GtkWidget:double-buffered:
    *
    * Whether the widget is double buffered.
    *
@@ -1231,7 +1231,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                       GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:margin-left
+   * GtkWidget:margin-left:
    *
    * Margin on left side of widget.
    *
@@ -1252,7 +1252,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                      GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:margin-right
+   * GtkWidget:margin-right:
    *
    * Margin on right side of widget.
    *
@@ -1273,7 +1273,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                      GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:margin-top
+   * GtkWidget:margin-top:
    *
    * Margin on top side of widget.
    *
@@ -1294,7 +1294,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                      GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:margin-bottom
+   * GtkWidget:margin-bottom:
    *
    * Margin on bottom side of widget.
    *
@@ -1315,7 +1315,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                      GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:margin
+   * GtkWidget:margin:
    *
    * Sets all four sides' margin at once. If read, returns max
    * margin on any side.
@@ -1350,7 +1350,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                   G_TYPE_NONE, 0);
 
   /**
-   * GtkWidget:hexpand
+   * GtkWidget:hexpand:
    *
    * Whether to expand horizontally. See gtk_widget_set_hexpand().
    *
@@ -1365,7 +1365,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:hexpand-set
+   * GtkWidget:hexpand-set:
    *
    * Whether to use the #GtkWidget:hexpand property. See gtk_widget_get_hexpand_set().
    *
@@ -1380,7 +1380,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:vexpand
+   * GtkWidget:vexpand:
    *
    * Whether to expand vertically. See gtk_widget_set_vexpand().
    *
@@ -1395,7 +1395,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:vexpand-set
+   * GtkWidget:vexpand-set:
    *
    * Whether to use the #GtkWidget:vexpand property. See gtk_widget_get_vexpand_set().
    *
@@ -1410,7 +1410,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:expand
+   * GtkWidget:expand:
    *
    * Whether to expand in both directions. Setting this sets both #GtkWidget:hexpand and #GtkWidget:vexpand
    *
@@ -3012,7 +3012,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
 		  GTK_TYPE_TOOLTIP);
 
   /**
-   * GtkWidget::popup-menu
+   * GtkWidget::popup-menu:
    * @widget: the object which received the signal
    *
    * This signal gets emitted whenever a widget should pop up a context
@@ -5444,7 +5444,7 @@ widget_new_accel_closure (GtkWidget *widget,
 }
 
 /**
- * gtk_widget_add_accelerator
+ * gtk_widget_add_accelerator:
  * @widget:       widget to install an accelerator on
  * @accel_signal: widget signal to emit on accelerator activation
  * @accel_group:  accel group for this widget, added to its toplevel
@@ -9511,7 +9511,7 @@ gtk_widget_get_size_request (GtkWidget *widget,
  * @width: new forced minimum width
  * @height: new forced minimum height
  * @old_width: location to store previous forced minimum width
- * @old_width: location to store previous forced minumum height
+ * @old_height: location to store previous forced minumum height
  *
  * Temporarily establishes a forced minimum size for a widget; this
  * is used by GtkWindow when calculating the size to add to the
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 19acb329ef..76f904959b 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -898,7 +898,7 @@ gtk_window_class_init (GtkWindowClass *klass)
 							 GTK_PARAM_READWRITE));
 
   /**
-   * GtkWindow:has-resize-grip
+   * GtkWindow:has-resize-grip:
    *
    * Whether the window has a corner resize grip.
    *