[gtk+] docs: point to suggested api for deprecated functions

[Stefan Kost <stefkost src gnome org>]

commit 32675db49086c42d9d58f572740c16e52243031d
Author: Stefan Sauer <ensonic users sf net>
Date:   Thu Jun 9 22:37:53 2016 +0200

    docs: point to suggested api for deprecated functions
    
    We deprecated a bunch of _focus_on_click() functions. Point to the new API
    in GtkWidget.

 gtk/gtkbutton.c            |   18 ++++++++++--------
 gtk/gtkcombobox.c          |    4 ++++
 gtk/gtkfilechooserbutton.c |   22 +++++++++++++---------
 3 files changed, 27 insertions(+), 17 deletions(-)
---
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 2d675a1..8c570a9 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -1432,7 +1432,7 @@ gtk_button_new_with_label (const gchar *label)
  * Returns: a new #GtkButton displaying the themed icon
  *
  * Since: 3.10
- **/
+ */
 GtkWidget*
 gtk_button_new_from_icon_name (const gchar *icon_name,
                               GtkIconSize  size)
@@ -1462,7 +1462,7 @@ gtk_button_new_from_icon_name (const gchar *icon_name,
  * Returns: a new #GtkButton
  *
  * Deprecated: 3.10: Use gtk_button_new_with_label() instead.
- **/
+ */
 GtkWidget*
 gtk_button_new_from_stock (const gchar *stock_id)
 {
@@ -1486,7 +1486,7 @@ gtk_button_new_from_stock (const gchar *stock_id)
  * Pressing Alt and that key activates the button.
  *
  * Returns: a new #GtkButton
- **/
+ */
 GtkWidget*
 gtk_button_new_with_mnemonic (const gchar *label)
 {
@@ -2161,7 +2161,7 @@ gtk_button_get_preferred_height_and_baseline_for_width (GtkWidget *widget,
  * is used.
  *
  * This will also clear any previously set labels.
- **/
+ */
 void
 gtk_button_set_label (GtkButton   *button,
                      const gchar *label)
@@ -2194,7 +2194,7 @@ gtk_button_set_label (GtkButton   *button,
  *
  * Returns: The text of the label widget. This string is owned
  * by the widget and must not be modified or freed.
- **/
+ */
 const gchar *
 gtk_button_get_label (GtkButton *button)
 {
@@ -2242,7 +2242,7 @@ gtk_button_set_use_underline (GtkButton *button,
  *
  * Returns: %TRUE if an embedded underline in the button label
  *               indicates the mnemonic accelerator keys.
- **/
+ */
 gboolean
 gtk_button_get_use_underline (GtkButton *button)
 {
@@ -2316,7 +2316,7 @@ gtk_button_get_use_stock (GtkButton *button)
  * Since: 2.4
  *
  * Deprecated: 3.20: Use gtk_widget_set_focus_on_click() instead
- **/
+ */
 void
 gtk_button_set_focus_on_click (GtkButton *button,
                               gboolean   focus_on_click)
@@ -2337,7 +2337,9 @@ gtk_button_set_focus_on_click (GtkButton *button,
  *               the mouse.
  *
  * Since: 2.4
- **/
+ *
+ * Deprecated: 3.20: Use gtk_widget_get_focus_on_click() instead
+ */
 gboolean
 gtk_button_get_focus_on_click (GtkButton *button)
 {
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 481c180..d0e2dd3 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -5012,6 +5012,8 @@ gtk_combo_box_get_entry_text_column (GtkComboBox *combo_box)
  * the main area of the application.
  *
  * Since: 2.6
+ *
+ * Deprecated: 3.20: Use gtk_widget_set_focus_on_click() instead
  */
 void
 gtk_combo_box_set_focus_on_click (GtkComboBox *combo_box,
@@ -5033,6 +5035,8 @@ gtk_combo_box_set_focus_on_click (GtkComboBox *combo_box,
  *     clicked with the mouse.
  *
  * Since: 2.6
+ *
+ * Deprecated: 3.20: Use gtk_widget_get_focus_on_click() instead
  */
 gboolean
 gtk_combo_box_get_focus_on_click (GtkComboBox *combo_box)
diff --git a/gtk/gtkfilechooserbutton.c b/gtk/gtkfilechooserbutton.c
index e4fdb61..957040d 100644
--- a/gtk/gtkfilechooserbutton.c
+++ b/gtk/gtkfilechooserbutton.c
@@ -1830,7 +1830,7 @@ model_add_special (GtkFileChooserButton *button)
 
   /* "To disable a directory, point it to the homedir."
    * See http://freedesktop.org/wiki/Software/xdg-user-dirs
-   **/
+   */
   if (g_strcmp0 (desktopdir, g_get_home_dir ()) != 0)
     {
       GtkTreePath *tree_path;
@@ -2997,7 +2997,7 @@ native_response_cb (GtkFileChooserNative *native,
  * Returns: a new button widget.
  *
  * Since: 2.6
- **/
+ */
 GtkWidget *
 gtk_file_chooser_button_new (const gchar          *title,
                             GtkFileChooserAction  action)
@@ -3029,7 +3029,7 @@ gtk_file_chooser_button_new (const gchar          *title,
  * Returns: a new button widget.
  *
  * Since: 2.6
- **/
+ */
 GtkWidget *
 gtk_file_chooser_button_new_with_dialog (GtkWidget *dialog)
 {
@@ -3048,7 +3048,7 @@ gtk_file_chooser_button_new_with_dialog (GtkWidget *dialog)
  * Modifies the @title of the browse dialog used by @button.
  *
  * Since: 2.6
- **/
+ */
 void
 gtk_file_chooser_button_set_title (GtkFileChooserButton *button,
                                   const gchar          *title)
@@ -3072,7 +3072,7 @@ gtk_file_chooser_button_set_title (GtkFileChooserButton *button,
  * Returns: a pointer to the browse dialog’s title.
  *
  * Since: 2.6
- **/
+ */
 const gchar *
 gtk_file_chooser_button_get_title (GtkFileChooserButton *button)
 {
@@ -3093,7 +3093,7 @@ gtk_file_chooser_button_get_title (GtkFileChooserButton *button)
  * Returns: an integer width (in characters) that the button will use to size itself.
  *
  * Since: 2.6
- **/
+ */
 gint
 gtk_file_chooser_button_get_width_chars (GtkFileChooserButton *button)
 {
@@ -3110,7 +3110,7 @@ gtk_file_chooser_button_get_width_chars (GtkFileChooserButton *button)
  * Sets the width (in characters) that @button will use to @n_chars.
  *
  * Since: 2.6
- **/
+ */
 void
 gtk_file_chooser_button_set_width_chars (GtkFileChooserButton *button,
                                         gint                  n_chars)
@@ -3132,7 +3132,9 @@ gtk_file_chooser_button_set_width_chars (GtkFileChooserButton *button,
  * application.
  *
  * Since: 2.10
- **/
+ *
+ * Deprecated: 3.20: Use gtk_widget_set_focus_on_click() instead
+ */
 void
 gtk_file_chooser_button_set_focus_on_click (GtkFileChooserButton *button,
                                            gboolean              focus_on_click)
@@ -3153,7 +3155,9 @@ gtk_file_chooser_button_set_focus_on_click (GtkFileChooserButton *button,
  *               the mouse.
  *
  * Since: 2.10
- **/
+ *
+ * Deprecated: 3.20: Use gtk_widget_get_focus_on_click() instead
+ */
 gboolean
 gtk_file_chooser_button_get_focus_on_click (GtkFileChooserButton *button)
 {