From 65748ca56c11c4978ca1ca3a317311af1d0d2725 Mon Sep 17 00:00:00 2001
From: J <799564+jaguilar@users.noreply.github.com>
Date: Sun, 10 Mar 2024 21:45:16 -0400
Subject: [PATCH] pybricks.common.Motor: Specify geartrain order.

---
 src/pybricks/_common.py    |  9 ++++++---
 src/pybricks/pupdevices.py | 15 ++++++++-------
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py
index 48a931ae..bb3e0bfc 100644
--- a/src/pybricks/_common.py
+++ b/src/pybricks/_common.py
@@ -390,15 +390,18 @@ def __init__(
                 turn when you give a positive speed value or
                 angle.
             gears (list):
-                List of gears linked to the motor.
+                List of gears linked to the motor. The gear connected
+                to the motor comes first and the gear connected to the output
+                comes last.
 
                 For example: ``[12, 36]`` represents a gear train with a
-                12-tooth and a 36-tooth gear. Use a list of lists for multiple
+                12-tooth gear connected to the motor and a 36-tooth gear
+                connected to the output. Use a list of lists for multiple
                 gear trains, such as ``[[12, 36], [20, 16, 40]]``.
 
                 When you specify a gear train, all motor commands and settings
                 are automatically adjusted to account for the resulting gear
-                ratio.  The motor direction remains unchanged by this.
+                ratio. The motor direction remains unchanged by this.
             reset_angle (bool):
                 Choose ``True`` to reset the rotation sensor value to the
                 absolute marker angle (between -180 and 179).
diff --git a/src/pybricks/pupdevices.py b/src/pybricks/pupdevices.py
index c9b28929..aa3eabbb 100644
--- a/src/pybricks/pupdevices.py
+++ b/src/pybricks/pupdevices.py
@@ -55,15 +55,18 @@ def __init__(
                 turn when you give a positive speed value or
                 angle.
             gears (list):
-                List of gears linked to the motor.
+                List of gears linked to the motor. The gear connected
+                to the motor comes first and the gear connected to the output
+                comes last.
 
                 For example: ``[12, 36]`` represents a gear train with a
-                12-tooth and a 36-tooth gear. Use a list of lists for multiple
+                12-tooth gear connected to the motor and a 36-tooth gear
+                connected to the output. Use a list of lists for multiple
                 gear trains, such as ``[[12, 36], [20, 16, 40]]``.
 
                 When you specify a gear train, all motor commands and settings
                 are automatically adjusted to account for the resulting gear
-                ratio.  The motor direction remains unchanged by this.
+                ratio. The motor direction remains unchanged by this.
             reset_angle (bool):
                 Choose ``True`` to reset the rotation sensor value to the
                 absolute marker angle (between -180 and 179).
@@ -124,12 +127,10 @@ def __init__(self, name: Optional[str] = None, timeout: int = 10000):
         """
 
     @overload
-    def name(self, name: str) -> None:
-        ...
+    def name(self, name: str) -> None: ...
 
     @overload
-    def name(self) -> str:
-        ...
+    def name(self) -> str: ...
 
     def name(self, *args):
         """name(name)