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

@@ -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)
 {

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)
 {

gtk/deprecated/gtkcolorsel.h

@@ -74,7 +74,7 @@ struct _GtkColorSelection
 {
   GtkBox parent_instance;
 
-  /* < private_data > */
+  /*< private >*/
   GtkColorSelectionPrivate *private_data;
 };
 

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,

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);

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)