[gtk+] docs: Convert GtkMenuShell comment to documentation

[David King <davidk src gnome org>]

commit 1e3e123c17c37055c097fbf8448c9a883cfc37a0
Author: David King <amigadave amigadave com>
Date:   Thu Nov 15 19:49:50 2012 +0000

    docs: Convert GtkMenuShell comment to documentation
    
    https://bugzilla.gnome.org/show_bug.cgi?id=448637

 gtk/gtkmenushell.c        |  106 ++++++++++++++++++++-------------------------
 gtk/gtkmenushellprivate.h |    7 +++-
 2 files changed, 53 insertions(+), 60 deletions(-)
---
diff --git a/gtk/gtkmenushell.c b/gtk/gtkmenushell.c
index dd5ef2f..3d3bc5e 100644
--- a/gtk/gtkmenushell.c
+++ b/gtk/gtkmenushell.c
@@ -34,6 +34,29 @@
  * in a list which can be navigated, selected, and activated by the
  * user to perform application functions. A #GtkMenuItem can have a
  * submenu associated with it, allowing for nested hierarchical menus.
+ *
+ * <refsect2 id="GtkMenuShell-Terminology">
+ * <title>Terminology</title>
+ * <para>
+ * A menu item can be "selected", this means that it is displayed
+ * in the prelight state, and if it has a submenu, that submenu
+ * will be popped up.
+ *
+ * A menu is "active" when it is visible onscreen and the user
+ * is selecting from it. A menubar is not active until the user
+ * clicks on one of its menuitems. When a menu is active,
+ * passing the mouse over a submenu will pop it up.
+ *
+ * There is also is a concept of the current menu and a current
+ * menu item. The current menu item is the selected menu item
+ * that is furthest down in the hierarchy. (Every active menu shell
+ * does not necessarily contain a selected menu item, but if
+ * it does, then the parent menu shell must also contain
+ * a selected menu item.) The current menu is the menu that
+ * contains the current menu item. It will always have a GTK
+ * grab and receive all key presses.
+ * </para>
+ * </refsect2>
  */
 #include "config.h"
 
@@ -85,65 +108,6 @@ enum {
   PROP_TAKE_FOCUS
 };
 
-/* Terminology:
- * 
- * A menu item can be "selected", this means that it is displayed
- * in the prelight state, and if it has a submenu, that submenu
- * will be popped up. 
- * 
- * A menu is "active" when it is visible onscreen and the user
- * is selecting from it. A menubar is not active until the user
- * clicks on one of its menuitems. When a menu is active,
- * passing the mouse over a submenu will pop it up.
- *
- * menu_shell->active_menu_item, is however, not an "active"
- * menu item (there is no such thing) but rather, the selected
- * menu item in that MenuShell, if there is one.
- *
- * There is also is a concept of the current menu and a current
- * menu item. The current menu item is the selected menu item
- * that is furthest down in the hierarchy. (Every active menu_shell
- * does not necessarily contain a selected menu item, but if
- * it does, then menu_shell->parent_menu_shell must also contain
- * a selected menu item. The current menu is the menu that 
- * contains the current menu_item. It will always have a GTK
- * grab and receive all key presses.
- *
- *
- * Action signals:
- *
- *  ::move_current (GtkMenuDirection *dir)
- *     Moves the current menu item in direction 'dir':
- *
- *       GTK_MENU_DIR_PARENT: To the parent menu shell
- *       GTK_MENU_DIR_CHILD: To the child menu shell (if this item has
- *          a submenu.
- *       GTK_MENU_DIR_NEXT/PREV: To the next or previous item
- *          in this menu.
- * 
- *     As a a bit of a hack to get movement between menus and
- *     menubars working, if submenu_placement is different for
- *     the menu and its MenuShell then the following apply:
- * 
- *       - For 'parent' the current menu is not just moved to
- *         the parent, but moved to the previous entry in the parent
- *       - For 'child', if there is no child, then current is
- *         moved to the next item in the parent.
- *
- *    Note that the above explanation of ::move_current was written
- *    before menus and menubars had support for RTL flipping and
- *    different packing directions, and therefore only applies for
- *    when text direction and packing direction are both left-to-right.
- * 
- *  ::activate_current (GBoolean *force_hide)
- *     Activate the current item. If 'force_hide' is true, hide
- *     the current menu item always. Otherwise, only hide
- *     it if menu_item->klass->hide_on_activate is true.
- *
- *  ::cancel ()
- *     Cancels the current selection
- */
-
 
 static void gtk_menu_shell_set_property      (GObject           *object,
                                               guint              prop_id,
@@ -1588,6 +1552,26 @@ gtk_menu_shell_select_submenu_first (GtkMenuShell *menu_shell)
   return FALSE;
 }
 
+/* Moves the current menu item in direction 'direction':
+ *
+ * - GTK_MENU_DIR_PARENT: To the parent menu shell
+ * - GTK_MENU_DIR_CHILD: To the child menu shell (if this item has a submenu).
+ * - GTK_MENU_DIR_NEXT/PREV: To the next or previous item in this menu.
+ *
+ * As a bit of a hack to get movement between menus and
+ * menubars working, if submenu_placement is different for
+ * the menu and its MenuShell then the following apply:
+ *
+ * - For 'parent' the current menu is not just moved to
+ *   the parent, but moved to the previous entry in the parent
+ * - For 'child', if there is no child, then current is
+ *   moved to the next item in the parent.
+ *
+ * Note that the above explanation of ::move_current was written
+ * before menus and menubars had support for RTL flipping and
+ * different packing directions, and therefore only applies for
+ * when text direction and packing direction are both left-to-right.
+ */
 static void
 gtk_real_menu_shell_move_current (GtkMenuShell         *menu_shell,
                                   GtkMenuDirectionType  direction)
@@ -1678,6 +1662,10 @@ gtk_real_menu_shell_move_current (GtkMenuShell         *menu_shell,
     }
 }
 
+/* Activate the current item. If 'force_hide' is true, hide
+ * the current menu item always. Otherwise, only hide
+ * it if menu_item->klass->hide_on_activate is true.
+ */
 static void
 gtk_real_menu_shell_activate_current (GtkMenuShell *menu_shell,
                                       gboolean      force_hide)
diff --git a/gtk/gtkmenushellprivate.h b/gtk/gtkmenushellprivate.h
index 40a858b..622f0fd 100644
--- a/gtk/gtkmenushellprivate.h
+++ b/gtk/gtkmenushellprivate.h
@@ -36,7 +36,12 @@ typedef enum
 struct _GtkMenuShellPrivate
 {
   GList *children;
-  GtkWidget *active_menu_item;
+
+  GtkWidget *active_menu_item; /* This is not an "active" menu item
+                                * (there is no such thing) but rather,
+                                * the selected menu item in that MenuShell,
+                                * if there is one.
+                                */
   GtkWidget *parent_menu_shell;
   GtkMenuTracker *tracker;    // if bound to a GMenuModel