[gtk+] [docs] GtkButton: Move documentation to inline comments

[Javier Jardón <jjardon src gnome org>]

commit 2ed1bab6bfffd22ea2fcdaaa696d25d299f02370
Author: Tadej Borovšak <tadeboro gmail com>
Date:   Sat May 1 19:17:51 2010 +0200

    [docs] GtkButton: Move documentation to inline comments
    
    Fixes https://bugzilla.gnome.org/show_bug.cgi?id=617386
    
    Signed-off-by: Javier Jardón <jjardon gnome org>

 docs/reference/gtk/tmpl/.gitignore     |    1 +
 docs/reference/gtk/tmpl/gtkbutton.sgml |  398 --------------------------------
 gtk/gtkbutton.c                        |  116 ++++++++--
 3 files changed, 103 insertions(+), 412 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 9e683a0..996aa55 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -1,6 +1,7 @@
 gtkbbox.sgml
 gtkbox.sgml
 gtkbuilder.sgml
+gtkbutton.sgml
 gtkhbox.sgml
 gtkiconview.sgml
 gtkmessagedialog.sgml
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index b0f41d5..a684c26 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -24,6 +24,20 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkbutton
+ * @Short_description: A widget that creates a signal when clicked on
+ * @Title: GtkButton
+ *
+ * The #GtkButton widget is generally used to attach a function to that is
+ * called when the button is pressed.  The various signals and how to use them
+ * are outlined below.
+ *
+ * The #GtkButton widget can hold any valid child widget.  That is it can hold
+ * most any other standard #GtkWidget.  The most commonly used child is the
+ * #GtkLabel.
+ */
+
 #include "config.h"
 #include <string.h>
 #include "gtkalignment.h"
@@ -268,7 +282,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * If the child of the button is a #GtkMisc or #GtkAlignment, this property 
    * can be used to control it's horizontal alignment. 0.0 is left aligned, 
    * 1.0 is right aligned.
-   * 
+   *
    * Since: 2.4
    */
   g_object_class_install_property (gobject_class,
@@ -287,7 +301,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * If the child of the button is a #GtkMisc or #GtkAlignment, this property 
    * can be used to control it's vertical alignment. 0.0 is top aligned, 
    * 1.0 is bottom aligned.
-   * 
+   *
    * Since: 2.4
    */
   g_object_class_install_property (gobject_class,
@@ -302,9 +316,9 @@ gtk_button_class_init (GtkButtonClass *klass)
 
   /**
    * GtkButton::image:
-   * 
+   *
    * The child widget to appear next to the button text.
-   * 
+   *
    * Since: 2.6
    */
   g_object_class_install_property (gobject_class,
@@ -319,7 +333,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * GtkButton:image-position:
    *
    * The position of the image relative to the text inside the button.
-   * 
+   *
    * Since: 2.10
    */
   g_object_class_install_property (gobject_class,
@@ -339,7 +353,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * @button: the object that received the signal
    *
    * Emitted when the button is pressed.
-   * 
+   *
    * Deprecated: 2.8: Use the #GtkWidget::button-press-event signal.
    */ 
   button_signals[PRESSED] =
@@ -356,7 +370,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * @button: the object that received the signal
    *
    * Emitted when the button is released.
-   * 
+   *
    * Deprecated: 2.8: Use the #GtkWidget::button-release-event signal.
    */ 
   button_signals[RELEASED] =
@@ -388,7 +402,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * @button: the object that received the signal
    *
    * Emitted when the pointer enters the button.
-   * 
+   *
    * Deprecated: 2.8: Use the #GtkWidget::enter-notify-event signal.
    */ 
   button_signals[ENTER] =
@@ -405,7 +419,7 @@ gtk_button_class_init (GtkButtonClass *klass)
    * @button: the object that received the signal
    *
    * Emitted when the pointer leaves the button.
-   * 
+   *
    * Deprecated: 2.8: Use the #GtkWidget::leave-notify-event signal.
    */ 
   button_signals[LEAVE] =
@@ -513,9 +527,9 @@ gtk_button_class_init (GtkButtonClass *klass)
 
   /**
    * GtkButton::image-spacing:
-   * 
+   *
    * Spacing in pixels between the image and label.
-   * 
+   *
    * Since: 2.10
    */
   gtk_widget_class_install_style_property (widget_class,
@@ -924,6 +938,14 @@ gtk_button_set_use_action_appearance (GtkButton *button,
     }
 }
 
+/**
+ * gtk_button_new:
+ *
+ * Creates a new #GtkButton widget. To add a child widget to the button,
+ * use gtk_container_add().
+ *
+ * Returns: The newly created #GtkButton widget.
+ */
 GtkWidget*
 gtk_button_new (void)
 {
@@ -1063,6 +1085,15 @@ gtk_button_construct_child (GtkButton *button)
 }
 
 
+/**
+ * gtk_button_new_with_label:
+ * @label: The text you want the #GtkLabel to hold.
+ *
+ * Creates a #GtkButton widget with a #GtkLabel child containing the given
+ * text.
+ *
+ * Returns: The newly created #GtkButton widget.
+ */
 GtkWidget*
 gtk_button_new_with_label (const gchar *label)
 {
@@ -1111,6 +1142,14 @@ gtk_button_new_with_mnemonic (const gchar *label)
   return g_object_new (GTK_TYPE_BUTTON, "label", label, "use-underline", TRUE,  NULL);
 }
 
+/**
+ * gtk_button_pressed:
+ * @button: The #GtkButton you want to send the signal to.
+ *
+ * Emits a #GtkButton::pressed signal to the given #GtkButton.
+ *
+ * Deprecated: 2.20: Use the #GtkWidget::button-press-event signal.
+ */
 void
 gtk_button_pressed (GtkButton *button)
 {
@@ -1120,6 +1159,14 @@ gtk_button_pressed (GtkButton *button)
   g_signal_emit (button, button_signals[PRESSED], 0);
 }
 
+/**
+ * gtk_button_released:
+ * @button: The #GtkButton you want to send the signal to.
+ *
+ * Emits a #GtkButton::released signal to the given #GtkButton.
+ *
+ * Deprecated: 2.20: Use the #GtkWidget::button-release-event signal.
+ */
 void
 gtk_button_released (GtkButton *button)
 {
@@ -1128,6 +1175,12 @@ gtk_button_released (GtkButton *button)
   g_signal_emit (button, button_signals[RELEASED], 0);
 }
 
+/**
+ * gtk_button_clicked:
+ * @button: The #GtkButton you want to send the signal to.
+ *
+ * Emits a #GtkButton::clicked signal to the given #GtkButton.
+ */
 void
 gtk_button_clicked (GtkButton *button)
 {
@@ -1136,6 +1189,14 @@ gtk_button_clicked (GtkButton *button)
   g_signal_emit (button, button_signals[CLICKED], 0);
 }
 
+/**
+ * gtk_button_enter:
+ * @button: The #GtkButton you want to send the signal to.
+ *
+ * Emits a #GtkButton::enter signal to the given #GtkButton.
+ *
+ * Deprecated: 2.20: Use the #GtkWidget::enter-notify-event signal.
+ */
 void
 gtk_button_enter (GtkButton *button)
 {
@@ -1144,6 +1205,14 @@ gtk_button_enter (GtkButton *button)
   g_signal_emit (button, button_signals[ENTER], 0);
 }
 
+/**
+ * gtk_button_leave:
+ * @button: The #GtkButton you want to send the signal to.
+ *
+ * Emits a #GtkButton::leave signal to the given #GtkButton.
+ *
+ * Deprecated: 2.20: Use the #GtkWidget::leave-notify-event signal.
+ */
 void
 gtk_button_leave (GtkButton *button)
 {
@@ -1152,6 +1221,17 @@ gtk_button_leave (GtkButton *button)
   g_signal_emit (button, button_signals[LEAVE], 0);
 }
 
+/**
+ * gtk_button_set_relief:
+ * @button: The #GtkButton you want to set relief styles of.
+ * @newstyle: The GtkReliefStyle as described above.
+ *
+ * Sets the relief style of the edges of the given #GtkButton widget.
+ * Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE.
+ * The default style is, as one can guess, GTK_RELIEF_NORMAL.
+ *
+ * <!-- FIXME: put pictures of each style -->
+ */
 void
 gtk_button_set_relief (GtkButton *button,
 		       GtkReliefStyle newrelief)
@@ -1166,6 +1246,14 @@ gtk_button_set_relief (GtkButton *button,
     }
 }
 
+/**
+ * gtk_button_get_relief:
+ * @button: The #GtkButton you want the #GtkReliefStyle from.
+ *
+ * Returns the current relief style of the given #GtkButton.
+ *
+ * Returns: The current #GtkReliefStyle
+ */
 GtkReliefStyle
 gtk_button_get_relief (GtkButton *button)
 {
@@ -2004,7 +2092,7 @@ gtk_button_get_use_stock (GtkButton *button)
  * gtk_button_set_focus_on_click:
  * @button: a #GtkButton
  * @focus_on_click: whether the button grabs focus when clicked with the mouse
- * 
+ *
  * Sets whether the button will grab focus when it is clicked with the mouse.
  * Making mouse clicks not grab focus is useful in places like toolbars where
  * you don't want the keyboard focus removed from the main area of the
@@ -2031,7 +2119,7 @@ gtk_button_set_focus_on_click (GtkButton *button,
 /**
  * gtk_button_get_focus_on_click:
  * @button: a #GtkButton
- * 
+ *
  * Returns whether the button grabs focus when it is clicked with the mouse.
  * See gtk_button_set_focus_on_click().
  *
@@ -2116,7 +2204,7 @@ gtk_button_get_alignment (GtkButton *button,
  * _gtk_button_set_depressed:
  * @button: a #GtkButton
  * @depressed: %TRUE if the button should be drawn with a recessed shadow.
- * 
+ *
  * Sets whether the button is currently drawn as down or not. This is 
  * purely a visual setting, and is meant only for use by derived widgets
  * such as #GtkToggleButton.