From a0fba6c2d1718a4fbf984e6d683fd0166bf5450b Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Mon, 17 Feb 2020 13:55:45 +0100
Subject: [PATCH] api/builtins/Control: Move stalled to control

This is a control status property, so move it to the control class. This way, it is hidden from the common motor methods, and DriveBases will be able to use it too.
---
 doc/api/ev3devices.rst |  2 --
 doc/api/motors.rst     | 10 ++++++----
 doc/api/pupdevices.rst |  2 --
 doc/api/robotics.rst   |  2 +-
 pybricks/builtins.py   | 23 +++++++----------------
 5 files changed, 14 insertions(+), 25 deletions(-)

diff --git a/doc/api/ev3devices.rst b/doc/api/ev3devices.rst
index 3ecfa54..189d290 100644
--- a/doc/api/ev3devices.rst
+++ b/doc/api/ev3devices.rst
@@ -18,8 +18,6 @@ Motor
 
     .. automethod:: pybricks.ev3devices.Motor.reset_angle
 
-    .. automethod:: pybricks.ev3devices.Motor.stalled
-
     .. rubric:: Action
 
     .. automethod:: pybricks.ev3devices.Motor.stop
diff --git a/doc/api/motors.rst b/doc/api/motors.rst
index 4d8d8d5..357ab4b 100644
--- a/doc/api/motors.rst
+++ b/doc/api/motors.rst
@@ -111,6 +111,12 @@ the settings.
 .. autoclass:: pybricks.builtins.Control
     :no-members:
 
+    .. rubric:: Status
+
+    .. automethod:: pybricks.builtins.Control.done
+
+    .. automethod:: pybricks.builtins.Control.stalled
+
     .. rubric:: Settings
 
     .. automethod:: pybricks.builtins.Control.limits
@@ -120,7 +126,3 @@ the settings.
     .. automethod:: pybricks.builtins.Control.target_tolerances
 
     .. automethod:: pybricks.builtins.Control.stall_tolerances
-
-    .. rubric:: Status
-
-    .. automethod:: pybricks.builtins.Control.done
diff --git a/doc/api/pupdevices.rst b/doc/api/pupdevices.rst
index dcf1cbf..2f08ad5 100644
--- a/doc/api/pupdevices.rst
+++ b/doc/api/pupdevices.rst
@@ -29,8 +29,6 @@ Motors with Rotation Sensors
 
     .. automethod:: pybricks.pupdevices.Motor.reset_angle
 
-    .. automethod:: pybricks.pupdevices.Motor.stalled
-
     .. rubric:: Action
 
     .. automethod:: pybricks.pupdevices.Motor.stop
diff --git a/doc/api/robotics.rst b/doc/api/robotics.rst
index 0587bd4..678f850 100644
--- a/doc/api/robotics.rst
+++ b/doc/api/robotics.rst
@@ -46,7 +46,7 @@
     .. rubric:: Advanced Settings
 
     The :meth:`.settings` method is used to adjust commonly used settings like
-    the default speed and acceleration for straight maneuvers and turns. 
+    the default speed and acceleration for straight maneuvers and turns.
     Use the following attributes to adjust more advanced control setttings.
 
     .. autoattribute:: pybricks.robotics.DriveBase.distance_control
diff --git a/pybricks/builtins.py b/pybricks/builtins.py
index 2af0f94..74b59da 100644
--- a/pybricks/builtins.py
+++ b/pybricks/builtins.py
@@ -94,21 +94,21 @@ class Control():
 
         Arguments:
             speed (:ref:`speed` or :ref:`linspeed`): If the controller
-                cannot reach this speed during at least ``stall_time``,
-                it is stalled.
-            time (:ref:`time`): See ``speed``.
+                cannot reach this speed for some ``time`` even with maximum
+                actuation, it is stalled.
+            time (:ref:`time`): How long the controller has to be below this
+                minimum ``speed`` before we say it is stalled.
         """
         pass
 
     def stalled(self):
         """Check whether the controller is currently stalled.
 
-        A controller is stalled when it cannot move even with the maximum
-        actuation signal.
+        A controller is stalled when it cannot reach the target speed or
+        position, even with the maximum actuation signal.
 
         Returns:
-            bool: ``True`` if the controller is stalled,``False`` if not.
-
+            bool: ``True`` if the controller is stalled, ``False`` if not.
         """
         pass
 
@@ -172,15 +172,6 @@ class Motor(DCMotor):
         """
         pass
 
-    def stalled(self):
-        """Check whether the motor is currently :ref:`stalled <stalled>`.
-
-        Returns:
-            bool: ``True`` if the motor is stalled, ``False`` if it is not.
-
-        """
-        pass
-
     def reset_angle(self, angle):
         """Reset the accumulated rotation angle of the motor.