Documentation fixes.

Sun Oct 13 18:50:14 2002  Soeren Sandmann  <sandmann@daimi.au.dk>

	* gtkmenu.c, gtkmenu.sgml, gtkitemfactory.c, gdkwindow.c,
	gtkwindow.c, gtkpaned.sgml, gtkdialog.c, gtkbox.h, gtkbutton.sgml,
	gtktreemodel.sgml,gtktable.sgml, gtktable.c:

	Documentation fixes.

	#85719, #90759, #95169, Owen Taylor;
	#89221, Yao Zhang, Matthias Clasen;
	#95592, Joost Faassen;
	#92637, Vitaly Tishkov;
	#94616, Ben Martin;
	#94772, sbaillie@bigpond.net.au;

6 files changed, 67 insertions, 14 deletions

diff --git a/gtk/gtkbox.h b/gtk/gtkbox.h
index 58b163ff59..11a6e46844 100644
--- a/gtk/gtkbox.h
+++ b/gtk/gtkbox.h
@@ -52,7 +52,8 @@ typedef struct _GtkBoxChild   GtkBoxChild;
 struct _GtkBox
 {
   GtkContainer container;
-  
+
+  /*< public >*/
   GList *children;
   gint16 spacing;
   guint homogeneous : 1;
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index f5c5614a09..0d2d3ac6c3 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -869,10 +869,10 @@ run_destroy_handler (GtkDialog *dialog, gpointer data)
  * @dialog: a #GtkDialog
  * 
  * Blocks in a recursive main loop until the @dialog either emits the
- * response signal, or is destroyed. If the dialog is destroyed,
- * gtk_dialog_run() returns #GTK_RESPONSE_NONE. Otherwise, it returns
- * the response ID from the "response" signal emission. Before
- * entering the recursive main loop, gtk_dialog_run() calls
+ * response signal, or is destroyed. If the dialog is destroyed during the call
+ * to gtk_dialog_run(), gtk_dialog_returns #GTK_RESPONSE_NONE.
+ * Otherwise, it returns the response ID from the "response" signal emission.
+ * Before entering the recursive main loop, gtk_dialog_run() calls
  * gtk_widget_show() on the dialog for you. Note that you still
  * need to show any children of the dialog yourself.
  *
diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c
index 5df097ae4f..5a82f9ff4e 100644
--- a/gtk/gtkitemfactory.c
+++ b/gtk/gtkitemfactory.c
@@ -1464,10 +1464,22 @@ ifactory_delete_popup_data (GtkObject	   *object,
  * @ifactory: a #GtkItemFactory of type #GTK_TYPE_MENU (see gtk_item_factory_new())
  * @x: the x position 
  * @y: the y position
- * @mouse_button: the mouse button which was pressed to initiate this action
- * @time: a timestamp for this action
+ * @mouse_button: the mouse button which was pressed to initiate the popup
+ * @time: the time at which the activation event occurred
  *
  * Pops up the menu constructed from the item factory at (@x, @y).
+ *
+ * The @mouse_button parameter should be the mouse button pressed to initiate
+ * the menu popup. If the menu popup was initiated by something other than
+ * a mouse button press, such as a mouse button release or a keypress,
+ * @mouse_button should be 0.
+ *
+ * The @time parameter should be the time stamp of the event that
+ * initiated the popup. If such an event is not available, use
+ * gtk_get_current_event_time() instead.
+ *
+ * The operation of the @mouse_button and the @time parameter is the same
+ * as the @button and @activation_time parameters for gtk_menu_popup().
  */
 void
 gtk_item_factory_popup (GtkItemFactory		*ifactory,
@@ -1487,12 +1499,24 @@ gtk_item_factory_popup (GtkItemFactory		*ifactory,
  *  the menu is unposted
  * @x: the x position 
  * @y: the y position
- * @mouse_button: the mouse button which was pressed to initiate this action
- * @time: a timestamp for this action
+ * @mouse_button: the mouse button which was pressed to initiate the popup
+ * @time: the time at which the activation event occurred
  *
  * Pops up the menu constructed from the item factory at (@x, @y). Callbacks
  * can access the @popup_data while the menu is posted via 
  * gtk_item_factory_popup_data() and gtk_item_factory_popup_data_from_widget().
+ *
+ * The @mouse_button parameter should be the mouse button pressed to initiate
+ * the menu popup. If the menu popup was initiated by something other than
+ * a mouse button press, such as a mouse button release or a keypress,
+ * @mouse_button should be 0.
+ *
+ * The @time parameter should be the time stamp of the event that
+ * initiated the popup. If such an event is not available, use
+ * gtk_get_current_event_time() instead.
+ *
+ * The operation of the @mouse_button and the @time parameters is the same
+ * as the @button and @activation_time parameters for gtk_menu_popup().
  */
 void
 gtk_item_factory_popup_with_data (GtkItemFactory	*ifactory,
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 9c247d7e6c..321c4ddcab 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -684,6 +684,32 @@ popup_grab_on_window (GdkWindow *window,
   return FALSE;
 }
 
+/**
+ * gtk_menu_popup:
+ * @menu: a #GtkMenu.
+ * @parent_menu_shell: the menu shell containing the triggering menu item, or %NULL
+ * @parent_menu_item: the menu item whose activation triggered the popup, or %NULL
+ * @func: a user supplied function used to position the menu, or %NULL
+ * @data: user supplied data to be passed to @func.
+ * @button: the mouse button which was pressed to initiate the event.
+ * @activate_time: the time at which the activation event occurred.
+ *
+ * Displays a menu and makes it available for selection.  Applications can use
+ * this function to display context-sensitive menus, and will typically supply
+ * %NULL for the @parent_menu_shell, @parent_menu_item, @func and @data 
+ * parameters. The default menu positioning function will position the menu
+ * at the current mouse cursor position.
+ *
+ * The @button parameter should be the mouse button pressed to initiate
+ * the menu popup. If the menu popup was initiated by something other than
+ * a mouse button press, such as a mouse button release or a keypress,
+ * @button should be 0.
+ *
+ * The @activate_time parameter should be the time stamp of the event that
+ * initiated the popup. If such an event is not available, use
+ * gtk_get_current_event_time() instead.
+ *
+ */
 void
 gtk_menu_popup (GtkMenu		    *menu,
 		GtkWidget	    *parent_menu_shell,
diff --git a/gtk/gtktable.c b/gtk/gtktable.c
index 8b473f19b1..f10578a949 100644
--- a/gtk/gtktable.c
+++ b/gtk/gtktable.c
@@ -200,28 +200,28 @@ gtk_table_class_init (GtkTableClass *class)
 					      CHILD_PROP_LEFT_ATTACH,
 					      g_param_spec_uint ("left_attach", 
 								 _("Left attachment"), 
-								 _("The leftmost column of the child"),
+								 _("The column number to attach the left side of the child to"),
 								 0, 65535, 0,
 								 G_PARAM_READWRITE));
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_RIGHT_ATTACH,
 					      g_param_spec_uint ("right_attach", 
 								 _("Right attachment"), 
-								 _("The rightmost column of the child"),
+								 _("the column number to attach the right side of a child widget to"),
 								 1, 65535, 1,
 								 G_PARAM_READWRITE));
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_TOP_ATTACH,
 					      g_param_spec_uint ("top_attach", 
 								 _("Top attachment"), 
-								 _("The uppermost row of the child"),
+								 _("The row number to attach the top of a child widget to"),
 								 0, 65535, 0,
 								 G_PARAM_READWRITE));
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_BOTTOM_ATTACH,
 					      g_param_spec_uint ("bottom_attach",
 								 _("Bottom attachment"), 
-								 _("The lowest row of the child"),
+								 _("The row number to attach the bottom of the child to"),
 								 1, 65535, 1,
 								 G_PARAM_READWRITE));
   gtk_container_class_install_child_property (container_class,
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index b3682d184a..de05e34f35 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -2116,7 +2116,9 @@ gtk_window_set_geometry_hints (GtkWindow       *window,
  * managers</link> allow GTK+ to disable these decorations, creating a
  * borderless window. If you set the decorated property to %FALSE
  * using this function, GTK+ will do its best to convince the window
- * manager not to decorate the window.
+ * manager not to decorate the window. Depending on the system, this
+ * function may not have any effect when called on a window that is
+ * already visible, so you should call it before calling gtk_window_show().
  *
  * On Windows, this function always works, since there's no window manager
  * policy involved.