Minimal examples for almost every API call (#31)

These are intended to be useful to display in isolation in autocomplete and parameter help where we don't show the full docs.

typeshed/stdlib/log.pyi

@@ -22,6 +22,8 @@ def set_labels(
 ) -> None:
     """Set up the log file header.
 
+    Example: ``log.set_labels('x', 'y', 'z', log.SECONDS)``
+
     Each call to this function with positional arguments will generate a new
     header entry into the log file.
 
@@ -45,9 +47,7 @@ def add(
 ) -> None:
     """Add a data row to the log by passing a dictionary of headers and values.
 
-    For example::
-
-        log.add({ "temp": temperature() })
+    Example: ``log.add({ 'temp': temperature() })``
 
     Each call to this function adds a row to the log.
 
@@ -64,9 +64,7 @@ def add(
 def add(**kwargs: Union[str, int, float]) -> None:
     """Add a data row to the log using keyword arguments.
 
-    For example::
-
-        log.add(temp=temperature())
+    Example: ``log.add(temp=temperature())``
 
     Each call to this function adds a row to the log.
 
@@ -82,6 +80,8 @@ def add(**kwargs: Union[str, int, float]) -> None:
 def delete(full=False):
     """Deletes the contents of the log, including headers.
 
+    Example: ``log.delete()``
+
     To add the log headers the ``set_labels`` function has to be called again
     after this.
 
@@ -93,8 +93,10 @@ def delete(full=False):
 def set_mirroring(serial: bool):
     """Mirrors the data logging activity to the serial output.
 
+    Example: ``log.set_mirroring(true)``
+
     Mirroring is disabled by default.
 
-    :param serial: Pass ``True`` to mirrors the data logging activity to the serial output, ``False`` to disable mirroring.
+    :param serial: Pass ``True`` to mirror the data logging activity to the serial output, ``False`` to disable mirroring.
     """
     ...

typeshed/stdlib/machine.pyi

@@ -6,24 +6,33 @@ from .microbit import MicroBitDigitalPin
 def unique_id() -> bytes:
     """Get a byte string with a unique identifier of a board.
 
+    Example: ``machine.unique_id()``
+
     :return: An identifier that varies from one board instance to another.
     """
     ...
 
 def reset() -> None:
-    """Reset the device in a manner similar to pushing the external RESET button."""
+    """Reset the device in a manner similar to pushing the external RESET button.
+
+    Example: ``machine.reset()``
+    """
     ...
 
 def freq() -> int:
     """Get the CPU frequency in hertz.
 
+    Example: ``machine.freq()``
+
     :return: The CPU frequency.
     """
     ...
 
 def disable_irq() -> Any:
     """Disable interrupt requests.
 
+    Example: ``interrupt_state = machine.disable_irq()``
+
     :return: the previous IRQ state which should be considered an opaque value
 
     The return value should be passed to the ``enable_irq`` function to restore
@@ -34,6 +43,8 @@ def disable_irq() -> Any:
 def enable_irq(state: Any) -> None:
     """Re-enable interrupt requests.
 
+    Example: ``machine.enable_irq(interrupt_state)``
+
     :param state: The value that was returned from the most recent call to the ``disable_irq`` function.
     """
     ...
@@ -43,6 +54,8 @@ def time_pulse_us(
 ) -> int:
     """Time a pulse on a pin.
 
+    Example: ``time_pulse_us(pin0, 1)``
+
     If the current input value of the pin is different to ``pulse_level``, the
     function first waits until the pin input becomes equal to
     ``pulse_level``, then times the duration that the pin is equal to

typeshed/stdlib/math.pyi

@@ -6,6 +6,8 @@ from typing import Tuple
 def acos(x: float) -> float:
     """Calculate the inverse cosine.
 
+    Example: ``math.acos(1)``
+
     :param x: A number
     :return: The inverse cosine of ``x``
     """
@@ -14,6 +16,8 @@ def acos(x: float) -> float:
 def asin(x: float) -> float:
     """Calculate the inverse sine.
 
+    Example: ``math.asin(0)``
+
     :param x: A number
     :return: The inverse sine of ``x``
     """
@@ -22,6 +26,8 @@ def asin(x: float) -> float:
 def atan(x: float) -> float:
     """Calculate the inverse tangent.
 
+    Example: ``math.atan(0)``
+
     :param x: A number
     :return: The inverse tangent of ``x``
     """
@@ -30,6 +36,8 @@ def atan(x: float) -> float:
 def atan2(y: float, x: float) -> float:
     """Calculate the principal value of the inverse tangent of ``y/x``.
 
+    Example: ``math.atan2(0, -1)``
+
     :param y: A number
     :param x: A number
     :return: The principal value of the inverse tangent of ``y/x``
@@ -39,6 +47,8 @@ def atan2(y: float, x: float) -> float:
 def ceil(x: float) -> float:
     """Round a number towards positive infinity.
 
+    Example: ``math.ceil(0.1)``
+
     :param x: A number
     :return: ``x`` rounded towards positive infinity.
     """
@@ -47,6 +57,8 @@ def ceil(x: float) -> float:
 def copysign(x: float, y: float) -> float:
     """Calculate ``x`` with the sign of ``y``.
 
+    Example: ``math.copysign(1, -1)``
+
     :param x: A number
     :param y: The source of the sign for the return value
     :return: ``x`` with the sign of ``y``
@@ -56,6 +68,8 @@ def copysign(x: float, y: float) -> float:
 def cos(x: float) -> float:
     """Calculate the cosine of ``x``.
 
+    Example: ``math.cos(0)``
+
     :param x: A number
     :return: The cosine of ``x``
     """
@@ -64,13 +78,17 @@ def cos(x: float) -> float:
 def degrees(x: float) -> float:
     """Convert radians to degrees.
 
+    Example: ``math.degrees(2 * math.pi)``
+
     :param x: A value in radians
     :return: The value converted to degrees"""
     ...
 
 def exp(x: float) -> float:
     """Calculate the exponential of ``x``.
 
+    Example: ``math.exp(1)``
+
     :param x: A number
     :return: The exponential of ``x``.
     """
@@ -79,6 +97,8 @@ def exp(x: float) -> float:
 def fabs(x: float) -> float:
     """Return the absolute value of ``x``.
 
+    Example: ``math.fabs(-0.1)``
+
     :param x: A number
     :return: The absolute value of ``x``
     """
@@ -87,6 +107,8 @@ def fabs(x: float) -> float:
 def floor(x: float) -> int:
     """Round a number towards negative infinity.
 
+    Example: ``math.floor(0.9)``
+
     :param x: A number
     :return: ``x`` rounded towards negative infinity.
     """
@@ -95,6 +117,8 @@ def floor(x: float) -> int:
 def fmod(x: float, y: float) -> float:
     """Calculate the remainder of ``x/y``.
 
+    Example: ``math.fmod(10, 3)``
+
     :param x: The numerator
     :param y: The denominator
     """
@@ -103,6 +127,8 @@ def fmod(x: float, y: float) -> float:
 def frexp(x: float) -> Tuple[float, int]:
     """Decomposes a floating-point number into its mantissa and exponent.
 
+    Example: ``mantissa, exponent = math.frexp(2)``
+
     The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e``
     exactly.  If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise
     the relation ``0.5 <= abs(m) < 1`` holds.
@@ -115,6 +141,8 @@ def frexp(x: float) -> Tuple[float, int]:
 def isfinite(x: float) -> bool:
     """Check if a value is finite.
 
+    Example: ``math.isfinite(float('inf'))``
+
     :param x: A number.
     :return: ``True`` if ``x`` is finite, ``False`` otherwise.
     """
@@ -123,6 +151,8 @@ def isfinite(x: float) -> bool:
 def isinf(x: float) -> bool:
     """Check if a value is infinite.
 
+    Example: ``math.isinf(float('-inf'))``
+
     :param x: A number.
     :return: ``True`` if ``x`` is infinite, ``False`` otherwise.
     """
@@ -131,13 +161,17 @@ def isinf(x: float) -> bool:
 def isnan(x: float) -> bool:
     """Check is a value is not-a-number (NaN).
 
+    Example: ``math.isnan(float('nan'))``
+
     :param x: A number
     :return: ``True`` if ``x`` is not-a-number (NaN), ``False`` otherwise."""
     ...
 
 def ldexp(x: float, exp: int) -> float:
     """Calculate ``x * (2**exp)``.
 
+    Example: ``math.ldexp(0.5, 2)``
+
     :param x: A number
     :param exp: Integer exponent
     :return: ``x * (2**exp)``
@@ -147,6 +181,8 @@ def ldexp(x: float, exp: int) -> float:
 def log(x: float, base: float = e) -> float:
     """Calculate the logarithm of ``x`` to the given base (defaults to natural logorithm).
 
+    Example: ``math.log(math.e)``
+
     With one argument, return the natural logarithm of x (to base e).
 
     With two arguments, return the logarithm of x to the given base, calculated as ``log(x)/log(base)``.
@@ -160,6 +196,8 @@ def log(x: float, base: float = e) -> float:
 def modf(x: float) -> Tuple[float, float]:
     """Calculate the fractional and integral parts of ``x``.
 
+    Example: ``fractional, integral = math.modf(1.5)``
+
     :param x: A number
     :return: A tuple of two floats representing the fractional then integral parts of ``x``.
 
@@ -170,6 +208,8 @@ def modf(x: float) -> Tuple[float, float]:
 def pow(x: float, y: float) -> float:
     """Returns ``x`` to the power of ``y``.
 
+    Example: ``math.pow(4, 0.5)``
+
     :param x: A number
     :param y: The exponent
     :return: ``x`` to the power of ``y``
@@ -179,6 +219,8 @@ def pow(x: float, y: float) -> float:
 def radians(x: float) -> float:
     """Convert a degrees to radians.
 
+    Example: ``math.radians(360)``
+
     :param x: A value in degrees
     :return: The value converted to radians
     """
@@ -187,6 +229,8 @@ def radians(x: float) -> float:
 def sin(x: float) -> float:
     """Calculate the sine of ``x``.
 
+    Example: ``math.sin(math.pi/2)``
+
     :param x: A number
     :return: The sine of ``x``
     """
@@ -195,6 +239,8 @@ def sin(x: float) -> float:
 def sqrt(x: float) -> float:
     """Calculate the square root of ``x``.
 
+    Example: ``math.sqrt(4)``
+
     :param x: A number
     :return: The square root of ``x``
     """
@@ -203,6 +249,8 @@ def sqrt(x: float) -> float:
 def tan(x: float) -> float:
     """Calculate the tangent of ``x``.
 
+    Example: ``math.tan(0)``
+
     :param x: A number
     :return: The tangent of ``x``.
     """
@@ -211,6 +259,8 @@ def tan(x: float) -> float:
 def trunc(x: float) -> int:
     """Round a number towards 0.
 
+    Example: ``math.trunc(-0.9)``
+
     :param x: A number
     :return: ``x`` rounded towards zero.
     """