[glib] GMenuModel: Flesh out the docs some more

[Matthias Clasen <matthiasc src gnome org>]

commit b153e38ff0b6fc7c6532e6dfc5b0f7305a360574
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Dec 13 23:16:25 2011 -0500

    GMenuModel: Flesh out the docs some more

 gio/gmenumodel.c |   12 +++++++++++-
 1 files changed, 11 insertions(+), 1 deletions(-)
---
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 171f2dc..64d99ae 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -100,7 +100,17 @@
  * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
  * and %G_MENU_LINK_SUBMENU.
  *
- * FIXME: explain how items are associated with actions.
+ * Items in a #GMenuModel represent active controls if they refer to
+ * an action that can get activated when the user interacts with the
+ * menu item. The reference to the action is encoded by the string id
+ * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
+ * identifies an action in an action group. Which action group(s) provide
+ * actions depends on the context in which the menu model is used.
+ * E.g. when the model is exported as the application menu of a
+ * #GtkApplication, actions can be application-wide or window-specific
+ * (and thus come from two different action groups). By convention, the
+ * application-wide actions have names that start with "app.", while the
+ * names of window-specific actions start with "win.".
  *
  * While a wide variety of stateful actions is possible, the following
  * is the minimum that is expected to be supported by all users of exported