[glib: 6/9] GAppInfo: Clarify that GAppInfo launch methods can spawn multiple instances

[Luca Bacci <lbacci src gnome org>]

commit 361b4a8fc9a498fc430aeb086074c397152be3de
Author: Luca Bacci <luca bacci982 gmail com>
Date:   Thu Jul 21 16:36:43 2022 +0200

    GAppInfo: Clarify that GAppInfo launch methods can spawn multiple instances
    
    ...of the application if many URI's are provided. This is important to note
    because the GAppLaunchContext signals may be emitted multiple times during
    a single launch operation.

 gio/gappinfo.c | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)
---
diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 17f453adab..d1a1a1d65c 100644
--- a/gio/gappinfo.c
+++ b/gio/gappinfo.c
@@ -651,7 +651,9 @@ g_app_info_supports_files (GAppInfo *appinfo)
  * Launches the application. This passes the @uris to the launched application
  * as arguments, using the optional @context to get information
  * about the details of the launcher (like what screen it is on).
- * On error, @error will be set accordingly.
+ * On error, @error will be set accordingly. If the application only supports
+ * one URI per invocation as part of their command-line, multiple instances
+ * of the application will be spawned.
  *
  * To launch the application without arguments pass a %NULL @uris list.
  *
@@ -1379,6 +1381,10 @@ g_app_launch_context_class_init (GAppLaunchContextClass *klass)
    * fails. The startup notification id is provided, so that the launcher
    * can cancel the startup notification.
    *
+   * Because a launch operation may involve spawning multiple instances of the
+   * target application, you should expect this signal to be emitted multiple
+   * times, one for each spawned instance.
+   *
    * Since: 2.36
    */
   signals[LAUNCH_FAILED] = g_signal_new (I_("launch-failed"),
@@ -1409,6 +1415,10 @@ g_app_launch_context_class_init (GAppLaunchContextClass *klass)
    * It is guaranteed that this signal is followed by either a #GAppLaunchContext::launched or
    * #GAppLaunchContext::launch-failed signal.
    *
+   * Because a launch operation may involve spawning multiple instances of the
+   * target application, you should expect this signal to be emitted multiple
+   * times, one for each spawned instance.
+   *
    * Since: 2.72
    */
   signals[LAUNCH_STARTED] = g_signal_new (I_("launch-started"),
@@ -1430,7 +1440,13 @@ g_app_launch_context_class_init (GAppLaunchContextClass *klass)
    * @platform_data: additional platform-specific data for this launch
    *
    * The #GAppLaunchContext::launched signal is emitted when a #GAppInfo is successfully
-   * launched. The @platform_data is an GVariant dictionary mapping
+   * launched.
+   *
+   * Because a launch operation may involve spawning multiple instances of the
+   * target application, you should expect this signal to be emitted multiple
+   * times, one time for each spawned instance.
+   *
+   * The @platform_data is an GVariant dictionary mapping
    * strings to variants (ie `a{sv}`), which contains additional,
    * platform-specific data about this launch. On UNIX, at least the
    * `pid` and `startup-notification-id` keys will be present.