[pitivi] dogtail tests: Document the improved_drag helper function

[Jean-FranÃois Fortin Tam <jfft src gnome org>]

commit 8879bac5bdc76cab2a42790a6a46d1be2a2ad54a
Author: Jean-FranÃois Fortin Tam <nekohayo gmail com>
Date:   Fri Jul 20 21:32:51 2012 -0400

    dogtail tests: Document the improved_drag helper function

 tests/dogtail_scripts/helper_functions.py |   22 ++++++++++++++++++----
 1 files changed, 18 insertions(+), 4 deletions(-)
---
diff --git a/tests/dogtail_scripts/helper_functions.py b/tests/dogtail_scripts/helper_functions.py
index e3f61f1..bec2a3e 100644
--- a/tests/dogtail_scripts/helper_functions.py
+++ b/tests/dogtail_scripts/helper_functions.py
@@ -125,21 +125,35 @@ class HelpFunc(BaseDogTail):
         return self.pitivi.children[0].children[0].children[2].children[1].children[3]
 
     def improved_drag(self, from_coords, to_coords, middle=[], absolute=True, moveAround=True):
-        dogtail.rawinput.press(from_coords[0], from_coords[1])
-        if moveAround:
-            dogtail.rawinput.relativeMotion(5, 5)
-            dogtail.rawinput.relativeMotion(-5, -5)
+        """
+        Allow dragging from a set of coordinates to another set of coords,
+        with an optional list of intermediate coordinates and the ability to
+        wiggle the mouse slightly at each set of coordinates.
+        """
+        # Choose the default type of motion calculation
         if absolute:
             fun = dogtail.rawinput.absoluteMotion
         else:
             fun = dogtail.rawinput.relativeMotion
+
+        # Do the initial click
+        dogtail.rawinput.press(from_coords[0], from_coords[1])
+        if moveAround:
+            dogtail.rawinput.relativeMotion(5, 5)
+            dogtail.rawinput.relativeMotion(-5, -5)
+
+        # Do all the intermediate move operations
         for mid in middle:
             fun(mid[0], mid[1])
             if moveAround:
                 dogtail.rawinput.relativeMotion(5, 5)
                 dogtail.rawinput.relativeMotion(-5, -5)
+
+        # Move to the final coordinates
         dogtail.rawinput.absoluteMotion(to_coords[0], to_coords[1])
         if moveAround:
             dogtail.rawinput.relativeMotion(5, 5)
             dogtail.rawinput.relativeMotion(-5, -5)
+
+        # Release the mouse button
         dogtail.rawinput.release(to_coords[0], to_coords[1])