doc/parameters: document stop types in table

Make more explicit how the stop types gradually add more resistance to motion.
pybricks · Apr 28, 2020 · 350b90d · 350b90d
1 parent c6f7b51
commit 350b90d
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 14 deletions.
diff --git a/doc/api/parameters.rst b/doc/api/parameters.rst
@@ -59,6 +59,31 @@
 .. autoclass:: pybricks.parameters.Stop
     :no-members:
 
+    The following table show how each stop type adds an extra level of
+    resistance to motion. In these examples, ``m`` is a
+    :class:`Motor <pybricks.ev3devices.Motor>` and
+    and ``d`` is a :class:`DriveBase <pybricks.robotics.DriveBase>`. The
+    examples also show how running at zero speed compares to these stop types.
+
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | | Type | | Friction | | Back | | Speed     |  | Angle kept | | Examples                              |
+    |        |            | | EMF  | | kept at 0 |  | at target  |                                         |
+    +========+============+========+=============+===============+=========================================+
+    | Coast  | +          |        |             |               | | ``m.stop()``                          |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.COAST)`` |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | Brake  | +          | +      |             |               | | ``m.brake()``                         |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.BRAKE)`` |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    |        | +          | +      | +           |               | | ``m.run(0)``                          |
+    |        |            |        |             |               | | ``d.drive(0, 0)``                     |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | Hold   | +          | +      | +           | +             | | ``m.hold()``                          |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.HOLD)``  |
+    |        |            |        |             |               | | ``d.straight(0)``                     |
+    |        |            |        |             |               | | ``d.straight(100)``                   |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+
 .. autoclass:: pybricks.parameters.Color
     :no-members:
 

diff --git a/pybricks/parameters.py b/pybricks/parameters.py
@@ -85,20 +85,6 @@ class Stop(_PybricksEnum):
 
         Keep controlling the motor to hold it at the commanded angle. This is
         only available on motors with encoders.
-
-    The stop type defines the resistance to motion after coming to a
-    standstill:
-
-    +-----------+-------------+------------------------------------------+
-    |Parameter  | Resistance  | Physical meaning                         |
-    +===========+=============+==========================================+
-    |Stop.COAST | low         | Friction                                 |
-    +-----------+-------------+------------------------------------------+
-    |Stop.BRAKE | medium      | Friction + Torque opposite to motion     |
-    +-----------+-------------+------------------------------------------+
-    |Stop.HOLD  | high        | Friction + Torque to hold commanded angle|
-    +-----------+-------------+------------------------------------------+
-
     """
 
     COAST = 0