doc/devices: simplify motor docs, reduce detail

Previously, we simplified the docs for initializing a motor. This commit also simplifies the docstrings for common motor methods, by leaving out details and optional arguments. Full details are still available on the dedicated motor page.

doc/api/ev3devices.rst

@@ -19,21 +19,29 @@ Motor
         # Initialize a motor with positive speed as counterclockwise
         right_motor = Motor(Port.B, Direction.COUNTERCLOCKWISE)
 
-    .. automethod:: pybricks.ev3devices.Motor.angle
+    .. automethod:: pybricks._instances.Motor.angle
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.reset_angle
+    .. automethod:: pybricks._instances.Motor.reset_angle
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.speed
+    .. automethod:: pybricks._instances.Motor.speed
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.stop
+    .. automethod:: pybricks._instances.Motor.stop
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.run
+    .. automethod:: pybricks._instances.Motor.run
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.run_time
+    .. automethod:: pybricks._instances.Motor.run_time
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.run_angle
+    .. automethod:: pybricks._instances.Motor.run_angle
+        :noindex:
 
-    .. automethod:: pybricks.ev3devices.Motor.run_target
+    .. automethod:: pybricks._instances.Motor.run_target
+        :noindex:
 
 
 Touch Sensor

doc/api/pupdevices.rst

@@ -21,32 +21,29 @@ Motor
 
     .. rubric:: Methods for motors with rotation sensors
 
-    .. automethod:: pybricks.pupdevices.Motor.angle
+    .. automethod:: pybricks._instances.Motor.angle
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.reset_angle
+    .. automethod:: pybricks._instances.Motor.reset_angle
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.speed
+    .. automethod:: pybricks._instances.Motor.speed
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.stop
+    .. automethod:: pybricks._instances.Motor.stop
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.run
+    .. automethod:: pybricks._instances.Motor.run
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.run_time
+    .. automethod:: pybricks._instances.Motor.run_time
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.run_angle
+    .. automethod:: pybricks._instances.Motor.run_angle
+        :noindex:
 
-    .. automethod:: pybricks.pupdevices.Motor.run_target
-
-    .. rubric:: Methods for all motors
-
-    .. automethod:: pybricks.pupdevices.Motor.dc
-
-        Example::
-
-            # Set the motor duty cycle to 75%.
-            example_motor.duty(75)
-
-    .. automethod:: pybricks.pupdevices.Motor.stop
+    .. automethod:: pybricks._instances.Motor.run_target
+        :noindex:
 
 
 Color and Distance Sensor

pybricks/_instances.py

@@ -2,7 +2,7 @@
 
 from .builtins import (Motor, Speaker, Display, Battery, ColorLight,
                        KeyPad, LightArray)
-from .parameters import Direction
+from .parameters import Direction, Stop
 from types import ModuleType
 
 
@@ -43,3 +43,86 @@ class Motor(Motor):
                 angle (*Default*: ``Direction.CLOCKWISE``).
         """
         pass
+
+    def angle(self):
+        """Get the rotation angle of the motor.
+
+        Returns:
+            :ref:`angle`: Motor angle.
+
+        """
+        pass
+
+    def reset_angle(self, angle):
+        """Reset the accumulated rotation angle of the motor.
+
+        Arguments:
+            angle (:ref:`angle`): Value to which the angle should be reset.
+        """
+        pass
+
+    def speed(self):
+        """Get the speed of the motor.
+
+        Returns:
+            :ref:`speed`: Motor speed.
+
+        """
+        pass
+
+    def stop(self, stop_type=Stop.COAST):
+        """stop()
+
+        Stop the motor.
+        """
+        pass
+
+    def run(self, speed):
+        """Keep the motor running at a constant speed.
+
+        Arguments:
+            speed (:ref:`speed`): Speed of the motor.
+        """
+        pass
+
+    def run_time(self, speed, time, stop_type=Stop.COAST, wait=True):
+        """run_time(speed, time)
+
+        Run the motor at a constant speed for a given amount of time.
+
+        Arguments:
+            speed (:ref:`speed`): Speed of the motor.
+            time (:ref:`time`): Duration of the maneuver.
+        """
+        pass
+
+    def run_angle(self, speed, rotation_angle,
+                  stop_type=Stop.COAST, wait=True):
+        """run_angle(speed, rotation_angle)
+
+        Rotate the motor at a constant speed by a given angle.
+
+        Arguments:
+            speed (:ref:`speed`): Speed of the motor.
+            rotation_angle (:ref:`angle`): Angle by which the motor should
+                                           rotate.
+        """
+        pass
+
+    def run_target(self, speed, target_angle, stop_type=Stop.COAST, wait=True):
+        """run_target(speed, target_angle)
+
+        Run the motor at a constant speed towards a given target angle. The
+        direction of rotation is automatically selected based on the target
+        angle.
+
+        Arguments:
+            speed (:ref:`speed`): Absolute speed of the motor. The direction
+                                  will be automatically selected based on the
+                                  target angle: it makes no difference if you
+                                  specify a positive or negative speed.
+            target_angle (:ref:`angle`): Target angle that the motor should
+                                         rotate to, regardless of its current
+                                         angle.
+        """
+        pass