[gnome-shell] main: Add a better comment about shifting the modal stack

[Jasper St. Pierre <jstpierre src gnome org>]

commit 73388f30fd638782c99bafa1f4829ff14978112b
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Wed Jan 2 09:19:41 2013 -0500

    main: Add a better comment about shifting the modal stack
    
    It took me a few minutes to realize why, so let's just add this
    in for future reference.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=690965

 js/ui/main.js |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)
---
diff --git a/js/ui/main.js b/js/ui/main.js
index 8c9136a..b907eb9 100644
--- a/js/ui/main.js
+++ b/js/ui/main.js
@@ -606,6 +606,21 @@ function popModal(actor, timestamp) {
         keybindingMode = record.keybindingMode;
         global.stage.set_key_focus(record.prevFocus);
     } else {
+        // If we have:
+        //     global.stage.set_focus(a);
+        //     Main.pushModal(b);
+        //     Main.pushModal(c);
+        //     Main.pushModal(d);
+        //
+        // then we have the stack:
+        //     [{ prevFocus: a, actor: b },
+        //      { prevFocus: b, actor: c },
+        //      { prevFocus: c, actor: d }]
+        //
+        // When actor c is destroyed/popped, if we only simply remove the
+        // record, then the focus stack will be [a, c], rather than the correct
+        // [a, b]. Shift the focus stack up before removing the record to ensure
+        // that we get the correct result.
         let t = modalActorFocusStack[modalActorFocusStack.length - 1];
         if (t.prevFocus)
             t.prevFocus.disconnect(t.prevFocusDestroyId);