From 0bee7ef984ffe80f4d00e15cd572dc7e8b2556c2 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Tue, 24 Mar 2020 12:12:49 +0100
Subject: [PATCH] doc: fix and clarify verbs

---
 pybricks/builtins.py   | 11 ++++++++---
 pybricks/pupdevices.py |  6 +++---
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/pybricks/builtins.py b/pybricks/builtins.py
index d79d9e8..2a657ca 100644
--- a/pybricks/builtins.py
+++ b/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.
diff --git a/pybricks/pupdevices.py b/pybricks/pupdevices.py
index e138024..a0cc9c7 100644
--- a/pybricks/pupdevices.py
+++ b/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.