doc: fix and clarify verbs

pybricks/builtins.py

@@ -31,7 +31,7 @@ class DCMotor:
         pass
 
     def stop(self):
-        """Stops the motor and let it spin freely.
+        """Stops the motor and lets it spin freely.
 
         The motor gradually stops due to friction."""
         pass
@@ -204,9 +204,10 @@ class Motor(DCMotor):
         pass
 
     def run(self, speed):
-        """Keeps the motor running at a constant speed.
+        """Runs the motor at a constant speed.
 
-        The motor keeps running until you give a new command.
+        The motor accelerates to the given speed and keeps running at this
+        speed until you give a new command.
 
         Arguments:
             speed (:ref:`speed`): Speed of the motor.
@@ -216,6 +217,10 @@ class Motor(DCMotor):
     def run_time(self, speed, time, then=Stop.HOLD, wait=True):
         """Runs the motor at a constant speed for a given amount of time.
 
+        The motor accelerates to the given speed, keeps running at this speed,
+        and then decelerates. The total maneuver lasts for exactly the given
+        amount of ``time``.
+
         Arguments:
             speed (:ref:`speed`): Speed of the motor.
             time (:ref:`time`): Duration of the maneuver.

pybricks/pupdevices.py

@@ -92,8 +92,8 @@ class ColorDistanceSensor:
         pass
 
     def distance(self):
-        """Measures the relative distance between the sensor and an object using
-        infrared light.
+        """Measures the relative distance between the sensor and an object
+        using infrared light.
 
         Returns:
             :ref:`relativedistance`: Relative distance ranging from 0 (closest)
@@ -102,7 +102,7 @@ class ColorDistanceSensor:
         pass
 
     def remote(self, channel, button_1=None, button_2=None):
-        """Make the sensor act like a Power Functions 1.0 IR remote.
+        """Makes the sensor act like a Power Functions 1.0 IR remote.
 
         Choose a channel and up to two buttons to "press". The infrared
         receiver behaves just as if responding to the real remote.