[gnome-shell] batch: Add old commit message as comment at top of file

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 50b59e0ca66fee1e81d34b12b37f42c4a16e5d06
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Tue Oct 13 14:41:22 2015 -0500

    batch: Add old commit message as comment at top of file
    
    This is a lightly-edited version of Ray's commit message in
    4902a600d52d24698611b8fefe1d4787f3e59089.

 js/gdm/batch.js |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)
---
diff --git a/js/gdm/batch.js b/js/gdm/batch.js
index b505c46..1b34d63 100644
--- a/js/gdm/batch.js
+++ b/js/gdm/batch.js
@@ -16,6 +16,34 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
+/*
+ * In order for transformation animations to look good, they need to be
+ * incremental and have some order to them (e.g., fade out hidden items,
+ * then shrink to close the void left over). Chaining animations in this way can
+ * be error-prone and wordy using just Tweener callbacks.
+ *
+ * The classes in this file help with this:
+ *
+ * - Task.  encapsulates schedulable work to be run in a specific scope.
+ *
+ * - ConsecutiveBatch.  runs a series of tasks in order and completes
+ *                      when the last in the series finishes.
+ *
+ * - ConcurrentBatch.  runs a set of tasks at the same time and completes
+ *                     when the last to finish completes.
+ *
+ * - Hold.  prevents a batch from completing the pending task until
+ *          the hold is released.
+ *
+ * The tasks associated with a batch are specified in a list at batch
+ * construction time as either task objects or plain functions.
+ * Batches are task objects, themselves, so they can be nested.
+ *
+ * These classes aren't specific to GDM, but were found to be unintuitive and so
+ * are not used elsewhere. These APIs may ultimately get dropped entirely and
+ * replaced by something else.
+ */
+
 const Lang = imports.lang;
 const Signals = imports.signals;