Move docs inline and expand them a bit.

2007-01-07  Matthias Clasen  <mclasen@redhat.com>

	* gtk/tmpl/gtkstatusbar.sgml: Move docs inline and
	expand them a bit.



svn path=/trunk/; revision=17100

4 files changed, 144 insertions, 50 deletions

diff --git a/ChangeLog b/ChangeLog
index f1c7923285..32fb18761c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-01-07  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkstatusbar.c: Move docs inline, and expand them 
+	a bit.
+
 2007-01-06  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtklabel.c: Make line wrapping work with width-chars
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 82d329c6c4..015ae1bd9a 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2007-01-07  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/tmpl/gtkstatusbar.sgml: Move docs inline and
+	expand them a bit.
+
 2007-01-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/tmpl/gtktextbuffer.sgml: Document rich text
diff --git a/docs/reference/gtk/tmpl/gtkstatusbar.sgml b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
index 66331aad4c..cbde13e52c 100644
--- a/docs/reference/gtk/tmpl/gtkstatusbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
@@ -19,12 +19,17 @@ Status bars in Gtk+ maintain a stack of messages. The message at
 the top of the each bar's stack is the one that will currently be displayed.
 </para>
 <para>
-Any messages added to a statusbar's stack must specify a <emphasis>context_id</emphasis>
-that is used to uniquely identify the source of a message. This context_id can be 
-generated by gtk_statusbar_get_context_id(), given a message and the
-statusbar that it will be added to. Note that messages are stored in a
-stack, and when choosing which message to display, the stack structure is
-adhered to, regardless of the context identifier of a message.
+Any messages added to a statusbar's stack must specify a <emphasis>context 
+id</emphasis> that is used to uniquely identify the source of a message. 
+This context id can be generated by gtk_statusbar_get_context_id(), given a 
+message and the statusbar that it will be added to. Note that messages are 
+stored in a stack, and when choosing which message to display, the stack 
+structure is adhered to, regardless of the context identifier of a message.
+</para>
+<para>
+One could say that a statusbar maintains one stack of messages for display
+purposes, but allows multiple message producers to maintain sub-stacks of
+the messages they produced (via context ids).
 </para>
 <para>
 Status bars are created using gtk_statusbar_new().
@@ -33,45 +38,40 @@ Status bars are created using gtk_statusbar_new().
 Messages are added to the bar's stack with gtk_statusbar_push().
 </para>
 <para>
-The message at the top of the stack can be removed using gtk_statusbar_pop(). A message can be removed from anywhere in the stack if its message_id was recorded at the time it was added. This is done using gtk_statusbar_remove().
+The message at the top of the stack can be removed using gtk_statusbar_pop(). 
+A message can be removed from anywhere in the stack if its message_id was 
+recorded at the time it was added. This is done using gtk_statusbar_remove().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term>#GtkDialog</term>
-<listitem><para>another way of reporting information to the user.</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
 
 <!-- ##### SECTION Stability_Level ##### -->
 
 
 <!-- ##### STRUCT GtkStatusbar ##### -->
 <para>
-Contains private data that should be modified with the functions described below.
+Contains private data that should be modified with the functions described 
+below.
 </para>
 
 
 <!-- ##### SIGNAL GtkStatusbar::text-popped ##### -->
 <para>
-Is emitted whenever a new message is popped off a statusbar's stack.
+
 </para>
 
-@statusbar: the object which received the signal.
-@context_id: the context id of the relevant message/statusbar.
-@text: the message that was just popped.
+@statusbar:
+@context_id:
+@text: 
 
 <!-- ##### SIGNAL GtkStatusbar::text-pushed ##### -->
 <para>
-Is emitted whenever a new message gets pushed onto a statusbar's stack.
+
 </para>
 
-@statusbar: the object which received the signal.
-@context_id: the context id of the relevant message/statusbar.
-@text: the message that was pushed.
+@statusbar: 
+@context_id:
+@text: 
 
 <!-- ##### ARG GtkStatusbar:has-resize-grip ##### -->
 <para>
@@ -85,69 +85,67 @@ Is emitted whenever a new message gets pushed onto a statusbar's stack.
 
 <!-- ##### FUNCTION gtk_statusbar_new ##### -->
 <para>
-Creates a new #GtkStatusbar ready for messages.
+
 </para>
 
-@Returns: the new #GtkStatusbar.
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_statusbar_get_context_id ##### -->
 <para>
-Returns a new context identifier, given a description of the actual context.
+
 </para>
 
-@statusbar: a #GtkStatusbar.
-@context_description: textual description of what context the new message is
-being used in.
-@Returns: an integer id.
+@statusbar: 
+@context_description:
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_statusbar_push ##### -->
 <para>
-Pushes a new message onto a statusbar's stack.
+
 </para>
 
-@statusbar: a #GtkStatusbar.
-@context_id: the message's context id, as returned by
-gtk_statusbar_get_context_id().
-@text: the message to add to the statusbar.
-@Returns: the message's new message id for use with gtk_statusbar_remove().
+@statusbar:
+@context_id:
+@text:
+@Returns:
 
 
 <!-- ##### FUNCTION gtk_statusbar_pop ##### -->
 <para>
-Removes the message at the top of a #GtkStatusBar's stack.
+
 </para>
 
-@statusbar: a #GtkStatusBar.
-@context_id: a context identifier.
+@statusbar: 
+@context_id:
 
 
 <!-- ##### FUNCTION gtk_statusbar_remove ##### -->
 <para>
-Forces the removal of a message from a statusbar's stack. The exact @context_id and @message_id must be specified.
+
 </para>
 
-@statusbar: a #GtkStatusBar.
-@context_id: a context identifier.
-@message_id: a message identifier, as returned by gtk_statusbar_push().
+@statusbar:
+@context_id:
+@message_id:
 
 
 <!-- ##### FUNCTION gtk_statusbar_set_has_resize_grip ##### -->
 <para>
-Sets whether the statusbar has a resize grip. %TRUE by default.
+
 </para>
 
-@statusbar: a #GtkStatusBar.
-@setting: %TRUE to have a resize grip.
+@statusbar:
+@setting: 
 
 
 <!-- ##### FUNCTION gtk_statusbar_get_has_resize_grip ##### -->
 <para>
-Returns whether the statusbar has a resize grip.
+
 </para>
 
-@statusbar: a #GtkStatusBar.
-@Returns: %TRUE if the statusbar has a resize grip.
+@statusbar:
+@Returns:
 
 
diff --git a/gtk/gtkstatusbar.c b/gtk/gtkstatusbar.c
index bdeeed91a8..7410e55848 100644
--- a/gtk/gtkstatusbar.c
+++ b/gtk/gtkstatusbar.c
@@ -142,6 +142,15 @@ gtk_statusbar_class_init (GtkStatusbarClass *class)
  							 P_("Whether the statusbar has a grip for resizing the toplevel"),
  							 TRUE,
  							 GTK_PARAM_READWRITE));
+
+  /** 
+   * GtkStatusbar::text-pushed:
+   * @statusbar: the object which received the signal.
+   * @context_id: the context id of the relevant message/statusbar.
+   * @text: the message that was pushed.
+   * 
+   * Is emitted whenever a new message gets pushed onto a statusbar's stack.
+   */
   statusbar_signals[SIGNAL_TEXT_PUSHED] =
     g_signal_new (I_("text_pushed"),
 		  G_OBJECT_CLASS_TYPE (class),
@@ -152,6 +161,15 @@ gtk_statusbar_class_init (GtkStatusbarClass *class)
 		  G_TYPE_NONE, 2,
 		  G_TYPE_UINT,
 		  G_TYPE_STRING);
+
+  /**
+   * GtkStatusbar::text-popped:
+   * @statusbar: the object which received the signal.
+   * @context_id: the context id of the relevant message/statusbar.
+   * @text: the message that was just popped.
+   *
+   * Is emitted whenever a new message is popped off a statusbar's stack.
+   */
   statusbar_signals[SIGNAL_TEXT_POPPED] =
     g_signal_new (I_("text_popped"),
 		  G_OBJECT_CLASS_TYPE (class),
@@ -207,6 +225,13 @@ gtk_statusbar_init (GtkStatusbar *statusbar)
   statusbar->keys = NULL;
 }
 
+/**
+ * gtk_statusbar_new:
+ *
+ * Creates a new #GtkStatusbar ready for messages.
+ *
+ * Returns: the new #GtkStatusbar
+ */
 GtkWidget* 
 gtk_statusbar_new (void)
 {
@@ -226,6 +251,18 @@ gtk_statusbar_update (GtkStatusbar *statusbar,
   gtk_label_set_text (GTK_LABEL (statusbar->label), text);
 }
 
+/**
+ * gtk_statusbar_get_context_id:
+ * @statusbar: a #GtkStatusbar
+ * @context_description: textual description of what context 
+ *                       the new message is being used in
+ *
+ * Returns a new context identifier, given a description 
+ * of the actual context. Note that the description is 
+ * <emphasis>not</emphasis> shown in the UI.
+ *
+ * Returns: an integer id
+ */
 guint
 gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
 			      const gchar  *context_description)
@@ -253,6 +290,18 @@ gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
   return *id;
 }
 
+/**
+ * gtk_statusbar_push:
+ * @statusbar: a #GtkStatusbar
+ * @context_id: the message's context id, as returned by
+ *              gtk_statusbar_get_context_id()
+ * @text: the message to add to the statusbar
+ * 
+ * Pushes a new message onto a statusbar's stack.
+ *
+ * Returns: a message id that can be used with 
+ *          gtk_statusbar_remove().
+ */
 guint
 gtk_statusbar_push (GtkStatusbar *statusbar,
 		    guint	  context_id,
@@ -279,6 +328,18 @@ gtk_statusbar_push (GtkStatusbar *statusbar,
   return msg->message_id;
 }
 
+/**
+ * gtk_statusbar_pop:
+ * @statusbar: a #GtkStatusBar
+ * @context_id: a context identifier
+ * 
+ * Removes the first message in the #GtkStatusBar's stack
+ * with the given context id. 
+ *
+ * Note that this may not change the displayed message, if 
+ * the message at the top of the stack has a different 
+ * context id.
+ */
 void
 gtk_statusbar_pop (GtkStatusbar *statusbar,
 		   guint	 context_id)
@@ -316,6 +377,15 @@ gtk_statusbar_pop (GtkStatusbar *statusbar,
 		 msg ? msg->text : NULL);
 }
 
+/**
+ * gtk_statusbar_remove:
+ * @statusbar: a #GtkStatusBar
+ * @context_id: a context identifier
+ * @message_id: a message identifier, as returned by gtk_statusbar_push()
+ *
+ * Forces the removal of a message from a statusbar's stack. 
+ * The exact @context_id and @message_id must be specified.
+ */
 void
 gtk_statusbar_remove (GtkStatusbar *statusbar,
 		      guint	   context_id,
@@ -357,6 +427,14 @@ gtk_statusbar_remove (GtkStatusbar *statusbar,
     }
 }
 
+/**
+ * gtk_statusbar_set_has_resize_grip:
+ * @statusbar: a #GtkStatusBar
+ * @setting: %TRUE to have a resize grip
+ *
+ * Sets whether the statusbar has a resize grip. 
+ * %TRUE by default.
+ */
 void
 gtk_statusbar_set_has_resize_grip (GtkStatusbar *statusbar,
 				   gboolean      setting)
@@ -387,6 +465,14 @@ gtk_statusbar_set_has_resize_grip (GtkStatusbar *statusbar,
     }
 }
 
+/**
+ * gtk_statusbar_get_has_resize_grip:
+ * @statusbar: a #GtkStatusBar
+ * 
+ * Returns whether the statusbar has a resize grip.
+ *
+ * Returns: %TRUE if the statusbar has a resize grip.
+ */
 gboolean
 gtk_statusbar_get_has_resize_grip (GtkStatusbar *statusbar)
 {