[gtk+] gtk: fix annotation syntax and missing some missing annotations

[Evan Nemerson <evann src gnome org>]

commit bda145b19f57bb2b8906fb8f1470b5a0fcd2b86e
Author: Evan Nemerson <evan nemerson com>
Date:   Mon May 26 09:32:32 2014 -0700

    gtk: fix annotation syntax and missing some missing annotations
    
    These changes clean up various errors and omissions resulting from
    either slightly incorrect G-I/gtk-doc syntax or missing documentation
    blocks.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=730745

 gtk/a11y/gtkcontainercellaccessible.c |    8 ++++++++
 gtk/a11y/gtktoplevelaccessible.c      |    6 ++++++
 gtk/deprecated/gtkcolorsel.h          |    2 +-
 gtk/deprecated/gtkstyle.c             |    4 ++--
 gtk/gtkclipboard.h                    |   29 +++++++++++++++++++++++++++++
 gtk/gtkwidget.c                       |   12 ++++++------
 6 files changed, 52 insertions(+), 9 deletions(-)
---
diff --git a/gtk/a11y/gtkcontainercellaccessible.c b/gtk/a11y/gtkcontainercellaccessible.c
index ea8ada0..4c2c804 100644
--- a/gtk/a11y/gtkcontainercellaccessible.c
+++ b/gtk/a11y/gtkcontainercellaccessible.c
@@ -162,6 +162,14 @@ gtk_container_cell_accessible_remove_child (GtkContainerCellAccessible *containe
   g_object_unref (child);
 }
 
+/**
+ * gtk_container_cell_accessible_get_children:
+ * @container: the container
+ *
+ * Get a list of children.
+ *
+ * Returns: (transfer none) (element-type Gtk.CellAccessible)
+ */
 GList *
 gtk_container_cell_accessible_get_children (GtkContainerCellAccessible *container)
 {
diff --git a/gtk/a11y/gtktoplevelaccessible.c b/gtk/a11y/gtktoplevelaccessible.c
index 037500b..b767667 100644
--- a/gtk/a11y/gtktoplevelaccessible.c
+++ b/gtk/a11y/gtktoplevelaccessible.c
@@ -298,6 +298,12 @@ gtk_toplevel_accessible_init (GtkToplevelAccessible *toplevel)
                               hide_event_watcher, toplevel, (GDestroyNotify) NULL);
 }
 
+/**
+ * gtk_toplevel_accessible_get_children:
+ *
+ * Returns: (transfer none) (element-type Gtk.Window): List of
+ *   children.
+ */
 GList *
 gtk_toplevel_accessible_get_children (GtkToplevelAccessible *accessible)
 {
diff --git a/gtk/deprecated/gtkcolorsel.h b/gtk/deprecated/gtkcolorsel.h
index 21f86b6..3ac8637 100644
--- a/gtk/deprecated/gtkcolorsel.h
+++ b/gtk/deprecated/gtkcolorsel.h
@@ -74,7 +74,7 @@ struct _GtkColorSelection
 {
   GtkBox parent_instance;
 
-  /* < private_data > */
+  /*< private >*/
   GtkColorSelectionPrivate *private_data;
 };
 
diff --git a/gtk/deprecated/gtkstyle.c b/gtk/deprecated/gtkstyle.c
index 6b759de..03e27e8 100644
--- a/gtk/deprecated/gtkstyle.c
+++ b/gtk/deprecated/gtkstyle.c
@@ -4077,7 +4077,7 @@ gtk_widget_get_default_style (void)
  *
  * Since: 2.20
  *
- * Deprecated: 3.0. This step is unnecessary with #GtkStyleContext.
+ * Deprecated: 3.0: This step is unnecessary with #GtkStyleContext.
  **/
 void
 gtk_widget_style_attach (GtkWidget *widget)
@@ -4514,7 +4514,7 @@ gtk_widget_modify_base (GtkWidget      *widget,
  *
  * Since: 2.12
  *
- * Deprecated: 3.0. Use gtk_widget_override_cursor() instead.
+ * Deprecated: 3.0: Use gtk_widget_override_cursor() instead.
  */
 void
 gtk_widget_modify_cursor (GtkWidget      *widget,
diff --git a/gtk/gtkclipboard.h b/gtk/gtkclipboard.h
index f7d27d7..13f7f7b 100644
--- a/gtk/gtkclipboard.h
+++ b/gtk/gtkclipboard.h
@@ -62,6 +62,22 @@ typedef void (* GtkClipboardTextReceivedFunc)     (GtkClipboard     *clipboard,
                                                   const gchar      *text,
                                                   gpointer          data);
 
+/**
+ * GtkClipboardRichTextReceivedFunc:
+ * @clipboard: the #GtkClipboard
+ * @format: The format of the rich text
+ * @text: (nullable) (type utf8): the rich text received, as
+ *   a UTF-8 encoded string, or %NULL if retrieving the data failed.
+ * @length: Length of the text.
+ * @data: (closure): the @user_data supplied to
+ *   gtk_clipboard_request_rich_text().
+ *
+ * A function to be called when the results of
+ * gtk_clipboard_request_rich_text() are received, or when the request
+ * fails.
+ *
+ * Since: 2.10
+ */
 typedef void (* GtkClipboardRichTextReceivedFunc) (GtkClipboard     *clipboard,
                                                    GdkAtom           format,
                                                   const guint8     *text,
@@ -84,6 +100,19 @@ typedef void (* GtkClipboardImageReceivedFunc)    (GtkClipboard     *clipboard,
                                                   GdkPixbuf        *pixbuf,
                                                   gpointer          data);
 
+/**
+ * GtkClipboardURIReceivedFunc:
+ * @clipboard: the #GtkClipboard
+ * @uris: (array zero-terminated=1): the received URIs
+ * @data: (closure): the @user_data supplied to
+ *   gtk_clipboard_request_uris().
+ *
+ * A function to be called when the results of
+ * gtk_clipboard_request_uris() are received, or when the request
+ * fails.
+ *
+ * Since: 2.14
+ */
 typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
                                                   gchar           **uris,
                                                   gpointer          data);
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index cf0505f..1aafe81 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1419,7 +1419,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * request, the margin will be added in addition to the size from
    * gtk_widget_set_size_request() for example.
    *
-   * Deprecated: 3.12. Use #GtkWidget:margin-start instead.
+   * Deprecated: 3.12: Use #GtkWidget:margin-start instead.
    *
    * Since: 3.0
    */
@@ -1442,7 +1442,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * request, the margin will be added in addition to the size from
    * gtk_widget_set_size_request() for example.
    *
-   * Deprecated: 3.12. Use #GtkWidget:margin-end instead.
+   * Deprecated: 3.12: Use #GtkWidget:margin-end instead.
    *
    * Since: 3.0
    */
@@ -1821,7 +1821,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * The ::state-changed signal is emitted when the widget state changes.
    * See gtk_widget_get_state().
    *
-   * Deprecated: 3.0. Use #GtkWidget::state-flags-changed instead.
+   * Deprecated: 3.0: Use #GtkWidget::state-flags-changed instead.
    */
   widget_signals[STATE_CHANGED] =
     g_signal_new (I_("state-changed"),
@@ -7820,7 +7820,7 @@ gtk_widget_reparent_fixup_child (GtkWidget *widget,
  * Moves a widget from one #GtkContainer to another, handling reference
  * count issues to avoid destroying the widget.
  *
- * Deprecated: 3.14. Use gtk_container_remove() and gtk_container_add().
+ * Deprecated: 3.14: Use gtk_container_remove() and gtk_container_add().
  **/
 void
 gtk_widget_reparent (GtkWidget *widget,
@@ -8784,7 +8784,7 @@ gtk_widget_get_state_flags (GtkWidget *widget)
  * of a widget (insensitive, prelighted, etc.) Usually you should set
  * the state using wrapper functions such as gtk_widget_set_sensitive().
  *
- * Deprecated: 3.0. Use gtk_widget_set_state_flags() instead.
+ * Deprecated: 3.0: Use gtk_widget_set_state_flags() instead.
  **/
 void
 gtk_widget_set_state (GtkWidget           *widget,
@@ -8839,7 +8839,7 @@ gtk_widget_set_state (GtkWidget           *widget,
  *
  * Since: 2.18
  *
- * Deprecated: 3.0. Use gtk_widget_get_state_flags() instead.
+ * Deprecated: 3.0: Use gtk_widget_get_state_flags() instead.
  */
 GtkStateType
 gtk_widget_get_state (GtkWidget *widget)