From a3b6507a15a6a2b46ef260445c4b0f5ba4cd1b43 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Mon, 2 Aug 2021 15:29:44 +0200
Subject: [PATCH] ubuiltins.bytes: Clarify docs.

---
 src/ubuiltins/__init__.py | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/src/ubuiltins/__init__.py b/src/ubuiltins/__init__.py
index 232ec39..7cf933d 100644
--- a/src/ubuiltins/__init__.py
+++ b/src/ubuiltins/__init__.py
@@ -126,21 +126,32 @@ class bytes:
         ...
 
     @overload
-    def __init__(self, source: Union[_int, _bytes, Iterable[_int]]) -> None:
+    def __init__(self, source: _int) -> None:
+        ...
+
+    @overload
+    def __init__(self, source: Union[_bytes, _bytearray, Iterable[_int]]) -> None:
         ...
 
     @overload
     def __init__(self, source: _str, encoding: _str) -> None:
         ...
 
-    @overload
-    def __init__(self, source: _str, encoding: _str, errors: _str) -> None:
-        ...
-
     def __init__(self, *args):
         """
-        Returns a new ``bytes`` object, which is an immutable sequence of integers
-        in the range ``0 <= x <= 255``.
+        Creates a new ``bytes`` object, which is a sequence of integers
+        in the range :math:`0 \leq x \leq 255`. This object is *immutable*,
+        which means that you *cannot* change its contents after you create it.
+
+           * If no argument is given, this creates an empty ``bytes`` object.
+           * If the ``source`` argument is an integer, this creates a ``bytes``
+             object of zeros. The argument specifies how many zeros.
+           * If ``source`` is a ``bytearray``, ``bytes`` object, or some other
+             iterable of integers, this creates a ``bytes``
+             object with the same byte sequence as the ``source`` argument.
+           * If ``source`` is a string, choose ``'utf8'`` as the ``encoding``
+             argument. Then this creates a ``bytes`` object containing the
+             encoded string.
         """
 
 
@@ -160,8 +171,8 @@ class bytearray:
     def __init__(self, *args):
         """
         Creates a new ``bytearray`` object, which is a sequence of integers
-        in the range ``0 <= x <= 255``. This object is mutable, which means
-        that you can change its contents after you create it.
+        in the range :math:`0 \leq x \leq 255`. This object is *mutable*, which
+        means that you *can* change its contents after you create it.
 
            * If no argument is given, this creates an empty ``bytearray``.
            * If the ``source`` argument is an integer, this creates a ``bytearray``