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

@@ -18,8 +18,6 @@ Motor
 
     .. automethod:: pybricks.ev3devices.Motor.reset_angle
 
-    .. automethod:: pybricks.ev3devices.Motor.stalled
-
     .. rubric:: Action
 
     .. automethod:: pybricks.ev3devices.Motor.stop

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

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

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

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.