[gnome-builder] supervisor: document slight of hand

[Christian Hergert <chergert src gnome org>]

commit a0898acd7ad1a6bcdb4da8e00058d229b38e79cb
Author: Christian Hergert <chergert redhat com>
Date:   Fri Oct 28 15:22:50 2016 -0700

    supervisor: document slight of hand

 libide/subprocess/ide-subprocess-supervisor.c |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)
---
diff --git a/libide/subprocess/ide-subprocess-supervisor.c b/libide/subprocess/ide-subprocess-supervisor.c
index 9cbe475..a7e6cd0 100644
--- a/libide/subprocess/ide-subprocess-supervisor.c
+++ b/libide/subprocess/ide-subprocess-supervisor.c
@@ -60,6 +60,12 @@ ide_subprocess_supervisor_reset (IdeSubprocessSupervisor *self)
     {
       g_autoptr(IdeSubprocess) subprocess = g_steal_pointer (&priv->subprocess);
 
+      /*
+       * We steal the subprocess first before possibly forcing exit from the
+       * subprocess so that when ide_subprocess_supervisor_wait_cb() is called
+       * it will not be able to match on (priv->subprocess == subprocess).
+       */
+
       if (!ide_subprocess_get_if_exited (subprocess) &&
           !ide_subprocess_get_if_signaled (subprocess))
         ide_subprocess_force_exit (subprocess);
@@ -327,6 +333,14 @@ ide_subprocess_supervisor_wait_cb (GObject      *object,
   }
 #endif
 
+  /*
+   * If we end up here in response to ide_subprocess_supervisor_reset() force
+   * exiting the process, we won't successfully match
+   * (priv->subprocess==subprocess) and therefore will not restart the process
+   * immediately (allowing the caller of ide_subprocess_supervisor_reset() to
+   * complete the operation.
+   */
+
   if (priv->subprocess == subprocess)
     {
       g_clear_object (&priv->subprocess);