Docs updates. (#72)

Scale docs are now duplicated due to overloads. This will result in a
translation key change but hopefully we can restore any translations.

Co-authored-by: Robert Knight <robert@microbit.org>

Author: microbit-matt-hillsdon

lang/en/typeshed/stdlib/microbit/__init__.pyi

@@ -1,7 +1,7 @@
 """Pins, images, sounds, temperature and volume.
 """
 
-from typing import Any, Callable, List, Optional, Tuple, overload
+from typing import Any, Callable, List, Optional, Tuple, Union, overload
 
 from _typeshed import ReadableBuffer
 
@@ -69,14 +69,41 @@ def panic(n: int) -> None:
 def reset() -> None:
     """Restart the board."""
 
+
+@overload
+def scale(value: float, from_: Tuple[float, float], to: Tuple[int, int]) -> int:
+    """Converts a value from a range to an integer range.
+
+    Example: ``volume = scale(accelerometer.get_x(), from_=(-2000, 2000), to=(0, 255))``
+
+    For example, to convert an accelerometer X value to a speaker volume.
+
+    If one of the numbers in the ``to`` parameter is a floating point
+    (i.e a decimal number like ``10.0``), this function will return a
+    floating point number.
+
+        temp_fahrenheit = scale(30, from_=(0.0, 100.0), to=(32.0, 212.0))
+
+    :param value: A number to convert.
+    :param from_: A tuple to define the range to convert from.
+    :param to: A tuple to define the range to convert to.
+    :return: The ``value`` converted to the ``to`` range.
+    """
+
+@overload
 def scale(value: float, from_: Tuple[float, float], to: Tuple[float, float]) -> float:
-    """Converts a value from a range to another range.
+    """Converts a value from a range to a floating point range.
+
+    Example: ``temp_fahrenheit = scale(30, from_=(0.0, 100.0), to=(32.0, 212.0))``
 
-    Example: ``temp_fahrenheit = scale(30, from_=(0, 100), to=(32, 212))``
+    For example, to convert temperature from a Celsius scale to Fahrenheit.
 
-    This can be useful to convert values between inputs and outputs, for example an accelerometer X value to a speaker volume.
+    If one of the numbers in the ``to`` parameter is a floating point
+    (i.e a decimal number like ``10.0``), this function will return a
+    floating point number.
+    If they are both integers (i.e ``10``), it will return an integer::
 
-    Negative scaling is also supported, for example ``scale(25, from_=(0, 100), to=(0, -200))`` will return ``-50``.
+        returns_int = scale(accelerometer.get_x(), from_=(-2000, 2000), to=(0, 255))
 
     :param value: A number to convert.
     :param from_: A tuple to define the range to convert from.

lang/en/typeshed/stdlib/music.pyi

@@ -1,6 +1,6 @@
 """Create and play melodies.
 """
-from typing import Tuple, Union, List
+from typing import Optional, Tuple, Union, List
 
 from .microbit import MicroBitDigitalPin, pin0
 
@@ -106,7 +106,7 @@ def get_tempo() -> Tuple[int, int]:
 
 def play(
     music: Union[str, List[str], Tuple[str, ...]],
-    pin: Union[MicroBitDigitalPin, None] = pin0,
+    pin: Optional[MicroBitDigitalPin] = pin0,
     wait: bool = True,
     loop: bool = False,
 ) -> None:
@@ -126,7 +126,7 @@ def play(
 def pitch(
     frequency: int,
     duration: int = -1,
-    pin: MicroBitDigitalPin = pin0,
+    pin: Optional[MicroBitDigitalPin] = pin0,
     wait: bool = True,
 ) -> None:
     """Play a note.
@@ -145,7 +145,7 @@ def pitch(
     """
     ...
 
-def stop(pin: MicroBitDigitalPin = pin0) -> None:
+def stop(pin: Optional[MicroBitDigitalPin] = pin0) -> None:
     """Stops all music playback on the built-in speaker and any pin outputting sound.
 
     Example: ``music.stop()``

lang/en/typeshed/stdlib/power.pyi

@@ -31,15 +31,20 @@ def deep_sleep(
 
     Example: ``power.deep_sleep(wake_on=(button_a, button_b))``
 
-    The program state is preserved and when it wakes up it will resume operation where it left off.
+    The program state is preserved and when it wakes up it will resume
+    operation where it left off.
 
     Deep Sleep mode will consume more battery power than Off mode.
 
     The wake up sources are configured via arguments.
 
-    If no wake up sources have been configured it will sleep until the reset button is pressed (which resets the Target MCU) or, in battery power, when the USB cable is inserted.
+    The board will always wake up when receiving UART data, when the reset
+    button is pressed (which resets the board) or, in battery power,
+    when the USB cable is inserted.
 
-    When the ``run_every`` parameter is set to ``True`` (the default), any function scheduled with ``microbit.run_every`` will still run while the board sleeps. When the scheduled time is reached the micro:bit will momentarily wake up to run the scheduled function and then automatically go back to sleep.
+    When the ``run_every`` parameter is set to ``True`` (the default), any
+    function scheduled with ``run_every`` will momentarily wake up the board
+    to run and when it finishes it will go back to sleep.
 
     :param ms: A time in milliseconds to wait before it wakes up.
     :param wake_on: A single instance or a tuple of pins and/or buttons to wake up the board, e.g. ``deep_sleep(wake_on=button_a)`` or ``deep_sleep(wake_on=(pin0, pin2, button_b))``.