Docs: clarify moveAbove(), moveBelow()

src/gameobjects/container/Container.js

@@ -818,6 +818,7 @@ var Container = new Class({
 
     /**
      * Moves a Game Object above another one within this Container.
+     * If the Game Object is already above the other, it isn't moved.
      *
      * These 2 Game Objects must already be children of this Container.
      *
@@ -841,6 +842,7 @@ var Container = new Class({
 
     /**
      * Moves a Game Object below another one within this Container.
+     * If the Game Object is already below the other, it isn't moved.
      *
      * These 2 Game Objects must already be children of this Container.
      *

src/scene/SceneManager.js

@@ -1536,6 +1536,7 @@ var SceneManager = new Class({
 
     /**
      * Moves a Scene so it is immediately above another Scene in the Scenes list.
+     * If the Scene is already above the other, it isn't moved.
      *
      * This means it will render over the top of the other Scene.
      *
@@ -1583,6 +1584,7 @@ var SceneManager = new Class({
 
     /**
      * Moves a Scene so it is immediately below another Scene in the Scenes list.
+     * If the Scene is already below the other, it isn't moved.
      *
      * This means it will render behind the other Scene.
      *

src/scene/ScenePlugin.js

@@ -836,9 +836,10 @@ var ScenePlugin = new Class({
     },
 
     /**
-     * Swaps the position of two scenes in the Scenes list, so that Scene B is directly above Scene A.
+     * Moves a Scene so it is immediately above another Scene in the Scenes list.
+     * If the Scene is already above the other, it isn't moved.
      *
-     * This controls the order in which they are rendered and updated.
+     * This means it will render over the top of the other Scene.
      *
      * @method Phaser.Scenes.ScenePlugin#moveAbove
      * @since 3.2.0
@@ -864,9 +865,10 @@ var ScenePlugin = new Class({
     },
 
     /**
-     * Swaps the position of two scenes in the Scenes list, so that Scene B is directly below Scene A.
+     * Moves a Scene so it is immediately below another Scene in the Scenes list.
+     * If the Scene is already below the other, it isn't moved.
      *
-     * This controls the order in which they are rendered and updated.
+     * This means it will render behind the other Scene.
      *
      * @method Phaser.Scenes.ScenePlugin#moveBelow
      * @since 3.2.0

src/structs/List.js

@@ -356,7 +356,9 @@ var List = new Class({
     },
 
     /**
-     * Moves the given array element above another one in the array.
+     * Moves an item above another one in the List.
+     * If the given item is already above the other, it isn't moved.
+     * Above means toward the end of the List.
      *
      * @method Phaser.Structs.List#moveAbove
      * @since 3.55.0
@@ -372,7 +374,9 @@ var List = new Class({
     },
 
     /**
-     * Moves the given array element below another one in the array.
+     * Moves an item below another one in the List.
+     * If the given item is already below the other, it isn't moved.
+     * Below means toward the start of the List.
      *
      * @method Phaser.Structs.List#moveBelow
      * @since 3.55.0

src/utils/array/MoveAbove.js

@@ -6,6 +6,8 @@
 
 /**
  * Moves the given array element above another one in the array.
+ * If the given element is already above the other, it isn't moved.
+ * Above means toward the end of the array.
  * The array is modified in-place.
  *
  * @function Phaser.Utils.Array.MoveAbove

src/utils/array/MoveBelow.js

@@ -6,6 +6,8 @@
 
 /**
  * Moves the given array element below another one in the array.
+ * If the given element is already below the other, it isn't moved.
+ * Below means toward the start of the array.
  * The array is modified in-place.
  *
  * @function Phaser.Utils.Array.MoveBelow