Improve param documentation

Author: dhalbert

.github/workflows/test.yml

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
 name: Run Tests
 
 on: [pull_request, push]

adafruit_simplemath.py

@@ -23,12 +23,21 @@
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_SimpleMath.git"
 
 
-def map_range(x, in_min, in_max, out_min, out_max):
+def map_range(
+    x: float, in_min: float, in_max: float, out_min: float, out_max: float
+) -> float:
     """
-    Maps a number from one range to another. Somewhat similar to the Arduino ``map()`` function, but
-    returns a floating point result, and constrains the output value to be between ``out_min`` and ``out_max``.
+    Maps a number from one range to another. Somewhat similar to the Arduino ``map()`` function,
+    but returns a floating point result, and constrains the output value to be between
+    ``out_min`` and ``out_max``.
+    If ``in_min`` is greater than ``in_max`` or ``out_min`` is greater than ``out_max``,
+    the corresponding range is reversed, allowing, for example, mapping a range of 0-10 to 50-0.
 
-    :return: Returns value mapped to new range
+    :param float in_min: Start value of input range.
+    :param float in_max: End value of input range.
+    :param float out_min: Start value of output range.
+    :param float out_max: End value of output range.
+    :return: Returns value mapped to new range.
     :rtype: float
     """
     in_range = in_max - in_min
@@ -46,14 +55,17 @@ def map_range(x, in_min, in_max, out_min, out_max):
     return min(max(mapped, out_max), out_min)
 
 
-def constrain(x, out_min, out_max):
-    """Constrains ``x`` to be within the inclusive range ``[out_min, out_max]``.
+def constrain(x: float, out_min: float, out_max: float) -> float:
+    """Constrains ``x`` to be within the inclusive range [``out_min``, ``out_max``].
     Sometimes called ``clip`` or ``clamp`` in other libraries.
     ``out_min`` should be less than or equal to ``out_max``.
     If ``x`` is less than ``out_min``, return ``out_min``.
     If ``x`` is greater than ``out_max``, return ``out_max``.
     Otherwise just return ``x``.
 
-    :return: Returns value constrained to given range
+    :param float out_min: Lower bound of output range.
+    :param float out_max: Upper bound of output range.
+    :return: Returns value constrained to given range.
+    :rtype: float
     """
     return max(out_min, min(x, out_max))

tests/constrain_test.py

@@ -4,6 +4,7 @@
 
 from adafruit_simplemath import constrain
 
+
 def test_constrain():
     assert constrain(1, 1, 10) == 1
     assert constrain(10, 1, 10) == 10

tests/map_range_test.py

@@ -4,6 +4,7 @@
 
 from adafruit_simplemath import map_range
 
+
 def test_map_range():
     assert map_range(1, 0, 10, 0, 100) == 10.0
     assert map_range(-1, 0, 10, 0, 100) == 0