Improve clarity of motor docs (#489)

Author: WasabiFan

README.rst

@@ -95,8 +95,8 @@ trying this out.
       else:
           leds.set_color(leds.led_groups.LEFT, leds.led_colors.RED)
 
-Running a motor
-~~~~~~~~~~~~~~~
+Running a single motor
+~~~~~~~~~~~~~~~~~~~~~~
 
 This will run a LEGO Large Motor at 75% of maximum speed for 5 rotations.
 
@@ -109,8 +109,8 @@ You can also run a motor for a number of degrees, an amount of time, or simply
 start it and let it run until you tell it to stop. Additionally, other units are
 also available. See the following pages for more information:
 
-- http://python-ev3dev.readthedocs.io/en/stretch/motors.html#ev3dev.motor.Motor.on_for_degrees
-- http://python-ev3dev.readthedocs.io/en/stretch/motors.html#units
+- http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/motors.html#ev3dev.motor.Motor.on_for_degrees
+- http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/motors.html#units
 
 Driving with two motors
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -119,17 +119,20 @@ The simplest drive control style is with the `MoveTank` class:
 
 .. code-block:: python
 
-    drive = MoveTank(OUTPUT_A, OUTPUT_B)
+    tank_drive = MoveTank(OUTPUT_A, OUTPUT_B)
 
     # drive in a turn for 5 rotations of the outer motor
-    # the first two parameters are percentages; they can also be unit classes.
-    drive.on_for_rotations(50, 75, 10)
+    # the first two parameters can be unit classes or percentages.
+    tank_drive.on_for_rotations(SpeedPercent(50), SpeedPercent(75), 10)
     
-    # drive in a different turn for 3 rotations of the outer motor
-    drive.on_for_rotations(60, 30, 3)
+    # drive in a different turn for 3 seconds
+    tank_drive.on_for_seconds(SpeedPercent(60), SpeedPercent(30), 3)
 
 There are also `MoveSteering` and `MoveJoystick` classes which provide different
-styles of control. Take a look at the corresponding documentation for more detail.
+styles of control. See the following pages for more information:
+
+- http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/motors.html#multiple-motor-groups
+- http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/motors.html#units
 
 Using text-to-speech
 ~~~~~~~~~~~~~~~~~~~~

docs/motors.rst

@@ -10,7 +10,7 @@ Motor classes
 Units
 -----
 
-Most methods which run motors with accept a ``speed_pct`` argument. While this can be provided as an integer which will be interpreted as a percentage of max speed, you can also specify an instance of any of the following classes, each of which represents a different unit system:
+Most methods which run motors with accept a ``speed`` or ``speed_pct`` argument. While this can be provided as an integer which will be interpreted as a percentage of max speed, you can also specify an instance of any of the following classes, each of which represents a different unit system:
 
 .. autoclass:: SpeedInteger
 .. autoclass:: SpeedPercent

ev3dev2/motor.py

@@ -1695,9 +1695,9 @@ class MoveTank(MotorSet):
 
     .. code:: python
 
-        drive = MoveTank(OUTPUT_A, OUTPUT_B)
+        tank_drive = MoveTank(OUTPUT_A, OUTPUT_B)
         # drive in a turn for 10 rotations of the outer motor
-        drive.on_for_rotations(50, 75, 10)
+        tank_drive.on_for_rotations(50, 75, 10)
     """
 
     def __init__(self, left_motor_port, right_motor_port, desc=None, motor_class=LargeMotor):
@@ -1847,17 +1847,19 @@ class MoveSteering(MoveTank):
     Controls a pair of motors simultaneously, via a single "steering" value.
 
     steering [-100, 100]:
-        * -100 means turn left as fast as possible,
+        * -100 means turn left on the spot (right motor at 100% forward, left motor at 100% backward),
         *  0   means drive in a straight line, and
-        *  100 means turn right as fast as possible.
+        *  100 means turn right on the spot (left motor at 100% forward, right motor at 100% backward).
     
+    "steering" can be any number between -100 and 100.
+
     Example:
 
     .. code:: python
 
-        drive = MoveSteering(OUTPUT_A, OUTPUT_B)
+        steering_drive = MoveSteering(OUTPUT_A, OUTPUT_B)
         # drive in a turn for 10 rotations of the outer motor
-        drive.on_for_rotations(-20, 75, 10)
+        steering_drive.on_for_rotations(-20, 75, 10)
     """
     def on_for_rotations(self, steering, speed_pct, rotations, brake=True, block=True):
         """
@@ -1899,9 +1901,9 @@ def get_speed_steering(self, steering, speed_pct):
         afterwards to make the motors move.
 
         steering [-100, 100]:
-            * -100 means turn left as fast as possible,
+            * -100 means turn left on the spot (right motor at 100% forward, left motor at 100% backward),
             *  0   means drive in a straight line, and
-            *  100 means turn right as fast as possible.
+            *  100 means turn right on the spot (left motor at 100% forward, right motor at 100% backward).
 
         speed_pct:
             The speed that should be applied to the outmost motor (the one
@@ -1939,7 +1941,25 @@ class MoveJoystick(MoveTank):
     def on(self, x, y, max_speed, radius=100.0):
         """
         Convert x,y joystick coordinates to left/right motor speed percentages
-        and move the motors
+        and move the motors.
+
+        This will use a classic "arcade drive" algorithm: a full-forward joystick
+        goes straight forward and likewise for full-backward. Pushing the joystick
+        all the way to one side will make it turn on the spot in that direction.
+        Positions in the middle will control how fast the vehicle moves and how
+        sharply it turns.
+
+        "x", "y":
+            The X and Y coordinates of the joystick's position, with
+            (0,0) representing the center position. X is horizontal and Y is vertical.
+        
+        max_speed (default 100%):
+            A percentage or other SpeedInteger, controlling the maximum motor speed.
+        
+        radius (default 100):
+            The radius of the joystick, controlling the range of the input (x, y) values.
+            e.g. if "x" and "y" can be between -1 and 1, radius should be set to "1".
+        
         """
 
         # If joystick is in the middle stop the tank