improve docs about animations, see #109

js/coins/view/MaxCoinsViewManager.ts

@@ -4,6 +4,10 @@
  * MaxCoinsViewManager creates and manages the node that is used to represent the set of 10k coins in the experiment. It
  * creates the node that represents this set of coins and animates it from the preparation area to the test box.
  *
+ * The animations here are pretty complex due to the need to move the cains in areas outside the bounds of the node in
+ * which they originate, to handle the large number of coins, and to handle the inflation animation that is used to
+ * represent the coins as they move from the preparation area to the measurement area.
+ *
  * @author John Blanco (PhET Interactive Simulations)
  * @author Agustín Vallejo
  */

js/coins/view/MultipleCoinsViewManager.ts

@@ -5,6 +5,9 @@
  * thus appear to originate there, and move into the measurement area.  This is used for the 10 and 100 coin cases.  The
  * 10k case is handled differently and is not included here.
  *
+ * The animations here are pretty complex due to the need to mask the coins in some cases, to handle different numbers,
+ * of coins, and to move the cains in areas outside the bounds of the node in which they originate.
+ *
  * @author John Blanco, PhET Interactive Simulations
  */
 

js/coins/view/SingleCoinViewManager.ts

@@ -5,6 +5,9 @@
  * experiment. This includes the animation of the coin moving from the preparation area to the measurement area, as
  * well as providing support for the coin flipping animation.
  *
+ * The animations here are pretty complex due to the need to mask the coins in some cases, to work with clip areas, and
+ * to move the cains in areas outside the bounds of the node in which they originate.
+ *
  * @author John Blanco, PhET Interactive Simulations
  */
 
@@ -146,7 +149,7 @@ class SingleCoinViewManager {
       // process consists of two animations, one to move the coin to the left edge of the test box while the test box is
       // potentially also moving, then a second one to move the coin into the box. The durations must be set up such
       // that the test box is in place before the 2nd animation begins or the coin won't end up in the right place.
-      const testBoxXOffset = forReprepare ? 180 : 250; // empirically determined
+      const testBoxXOffset = forReprepare ? 180 : 250; // empirically determined, adjust as needed
       const leftOfTestBoxGlobal = singleCoinTestBox.parentToGlobalPoint(
         singleCoinTestBox.center.minusXY( testBoxXOffset, 0 )
       );