From 4da4ce8f7c5da75be396cdf961635cde58542e48 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Tue, 6 Dec 2022 16:38:31 +0100
Subject: [PATCH] pybricks.robotics.DriveBase: Add clarifying comments.

Fixes https://github.com/pybricks/support/issues/698
---
 doc/main/robotics.rst    |  7 +++++++
 src/pybricks/robotics.py | 10 +++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/main/robotics.rst b/doc/main/robotics.rst
index 56dbfac..d7c7d10 100644
--- a/doc/main/robotics.rst
+++ b/doc/main/robotics.rst
@@ -52,6 +52,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.stalled
 
+    .. _measuring:
+
     .. rubric:: Measuring and validating the robot dimensions
 
     As a first estimate, you can measure the ``wheel_diameter`` and the
@@ -59,6 +61,11 @@
     effectively touch the ground, you can estimate the ``axle_track`` as
     the distance between the midpoint of the wheels.
 
+    If you don't have a ruler, you can use a LEGO beam to measure. The
+    center-to-center distance of the holes is 8 mm. For some tyres, the
+    diameter is printed on the side. For example, 62.4 x 20 means that the
+    diameter is 62.4mm and that the width is 20 mm.
+
     In practice, most wheels compress slightly under the weight of your robot.
     To verify, make your robot drive 1000 mm using ``my_robot.straight(1000)``
     and measure how far it really traveled. Compensate as follows:
diff --git a/src/pybricks/robotics.py b/src/pybricks/robotics.py
index f898cb3..2cc592b 100644
--- a/src/pybricks/robotics.py
+++ b/src/pybricks/robotics.py
@@ -28,8 +28,12 @@ class DriveBase:
 
     **Positive** angles and turn rates mean turning **right**.
     **Negative** means **left**. So when viewed from the top,
-    positive means clockwise and negative means counterclockwise.
+    positive means clockwise and negative means counterclockwise. If desired,
+    you can flip this convention by reversing the ``left_motor`` and
+    ``right_motor`` when you initialize this class.
 
+    See the `measuring`_ section for tips to measure and adjust the diameter
+    and axle track values.
     """
 
     distance_control = _common.Control()
@@ -139,6 +143,10 @@ class DriveBase:
 
         If you give no arguments, this returns the current values as a tuple.
 
+        The default values are automatically configured based on your wheel
+        diameter and axle track. They are selected such that your robot
+        drives at about 40% of its maximum speed.
+
         Arguments:
             straight_speed (Number, mm/s): Straight-line speed of the robot.
             straight_acceleration (Number, mm/s²): Straight-line