[gtk+/wip/gmenu] GtkApplication: document relationship to gdkthreads

[Ryan Lortie <ryanl src gnome org>]

commit 23eef0a8b512fa2a7111f4606702c5c079a1d199
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Dec 17 13:17:31 2011 -0500

    GtkApplication: document relationship to gdkthreads

 gtk/gtkapplication.c       |    9 +++++++++
 gtk/gtkapplicationwindow.c |    4 ++++
 2 files changed, 13 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 307ee6f..b6fe1b8 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -62,6 +62,15 @@
  * While GtkApplication works fine with plain #GtkWindows, it is recommended
  * to use it together with #GtkApplicationWindow.
  *
+ * When GDK threads are enabled, GtkApplication will acquire the GDK
+ * lock when invoking actions that arrive from other processes.  The GDK
+ * lock is not touched for local action invocations.  In order to have
+ * actions invoked in a predictable context it is therefore recommended
+ * that the GDK lock be held while invoking actions locally with
+ * g_action_group_activate_action().  The same applies to actions
+ * associated with #GtkApplicationWindow and to the 'activate' and
+ * 'open' #GApplication methods.
+ *
  * To set an application menu on a GtkApplication, use
  * g_application_set_app_menu(). The #GMenuModel that this function
  * expects is usually constructed using #GtkBuilder, as seen in the
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 31071d7..829d959 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -54,6 +54,10 @@
  * prefix.  Actions must be addressed with the prefixed name when
  * referring to them from a #GMenuModel.
  *
+ * As with #GtkApplication, the GDK lock will be acquired when
+ * processing actions arriving from other processes and should therefore
+ * be held when activating actions locally (if GDK threads are enabled).
+ *
  * The settings #GtkSettings:gtk-shell-shows-app-menu and
  * #GtkSettings:gtk-shell-shows-menubar tell GTK+ whether the
  * desktop environment is showing the application menu and menubar