From 923e8caf842e3c9cf7b702b56bbd26a18ce22a7a Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Mon, 19 Jul 2021 19:24:48 +0200
Subject: [PATCH] ubuiltins: Organize exceptions.

---
 doc/main/micropython/exceptions.rst | 109 ++++++++++++++++++++--------
 src/ubuiltins/__init__.py           |  12 +--
 2 files changed, 86 insertions(+), 35 deletions(-)

diff --git a/doc/main/micropython/exceptions.rst b/doc/main/micropython/exceptions.rst
index 6b6e040..ef907cf 100644
--- a/doc/main/micropython/exceptions.rst
+++ b/doc/main/micropython/exceptions.rst
@@ -1,67 +1,116 @@
 Exceptions and error codes
 =====================================================
 
-.. autoclass:: ubuiltins.BaseException
 
-.. autoclass:: ubuiltins.Exception
+List of all exceptions
+----------------------
+
+This section lists all available exceptions in alphabetical order.
 
 .. autoclass:: ubuiltins.ArithmeticError
-
-.. autoclass:: ubuiltins.LookupError
+    :no-members:
 
 .. autoclass:: ubuiltins.AssertionError
+    :no-members:
 
 .. autoclass:: ubuiltins.AttributeError
+    :no-members:
+
+.. autoclass:: ubuiltins.BaseException
+    :no-members:
 
 .. autoclass:: ubuiltins.EOFError
+    :no-members:
+
+.. autoclass:: ubuiltins.Exception
+    :no-members:
 
 .. autoclass:: ubuiltins.GeneratorExit
+    :no-members:
 
 .. autoclass:: ubuiltins.ImportError
+    :no-members:
 
 .. autoclass:: ubuiltins.IndentationError
+    :no-members:
 
 .. autoclass:: ubuiltins.IndexError
-
-.. autoclass:: ubuiltins.KeyError
+    :no-members:
 
 .. autoclass:: ubuiltins.KeyboardInterrupt
+    :noindex:
+    :no-members:
+
+    See also `stopping a program`_.
+
+.. autoclass:: ubuiltins.KeyError
+    :no-members:
+
+.. autoclass:: ubuiltins.LookupError
+    :no-members:
 
 .. autoclass:: ubuiltins.MemoryError
+    :no-members:
 
 .. autoclass:: ubuiltins.NameError
+    :no-members:
 
 .. autoclass:: ubuiltins.NotImplementedError
-
-.. autoclass:: ubuiltins.OverflowError
-
-.. autoclass:: ubuiltins.RuntimeError
-
-.. autoclass:: ubuiltins.StopIteration
-
-.. autoclass:: ubuiltins.SyntaxError
-
-.. autoclass:: ubuiltins.SystemExit
-
-.. autoclass:: ubuiltins.TypeError
-
-.. autoclass:: ubuiltins.ValueError
-
-.. autoclass:: ubuiltins.ZeroDivisionError
-
-OSError
---------
+    :no-members:
 
 .. autoclass:: ubuiltins.OSError
+    :noindex:
 
+    See the `OSError`_ section for additional details.
 
-.. rubric:: uerrno module
+.. autoclass:: ubuiltins.OverflowError
+    :no-members:
 
-.. module:: uerrno
+.. autoclass:: ubuiltins.RuntimeError
+    :no-members:
+
+.. autoclass:: ubuiltins.StopIteration
+    :no-members:
+
+.. autoclass:: ubuiltins.SyntaxError
+    :no-members:
+
+.. autoclass:: ubuiltins.SystemExit
+    :noindex:
+    :no-members:
+
+    See also `stopping a program`_.
+
+.. autoclass:: ubuiltins.TypeError
+    :no-members:
+
+.. autoclass:: ubuiltins.ValueError
+    :no-members:
+
+.. autoclass:: ubuiltins.ZeroDivisionError
+    :no-members:
+
+.. _stopping a program:
+
+Stopping programs
+-----------------
+
+.. autoclass:: ubuiltins.KeyboardInterrupt
+    :no-members:
+
+.. autoclass:: ubuiltins.SystemExit
+    :no-members:
+
+.. _OSError:
+
+Using ``OSError`` with :mod:`uerrno`
+------------------------------------
 
 The ``errno`` attribute of an ``OSError`` indicates why the exception was
-raised. It has one of the following values, which can be imported from the
-``uerrno`` module:
+raised. This attribute has one of the following values, which can be imported
+from the ``uerrno`` module. See also :ref:`this example <device_detection>`.
+
+.. module:: uerrno
 
 .. autodata:: uerrno.EAGAIN
 
@@ -86,6 +135,8 @@ raised. It has one of the following values, which can be imported from the
 Examples
 ---------------------
 
+.. _device_detection:
+
 Detect devices using ``OSError``
 *****************************************
 
diff --git a/src/ubuiltins/__init__.py b/src/ubuiltins/__init__.py
index 9a947a8..2eda861 100644
--- a/src/ubuiltins/__init__.py
+++ b/src/ubuiltins/__init__.py
@@ -866,7 +866,7 @@ class BaseException:
 
 class Exception(BaseException):
     """
-    All built-in, non-system-exiting exceptions are derived from this class.
+    All built-in exceptions are derived from this class.
 
     All user-defined exceptions should also be derived from this class.
     """
@@ -916,7 +916,7 @@ class GeneratorExit(BaseException):
 
 class ImportError(Exception):
     """
-    Raised when the ``import`` statement has troubles trying to load a module.
+    Raised when the ``import`` statement is unable to load a module.
     """
 
 
@@ -975,7 +975,7 @@ class OSError(Exception):
 
     errno: _int
     """
-    Specifies which kind of ``OSError`` occurred, as listed below.
+    Specifies which kind of ``OSError`` occurred, as listed :ref:`here <OSError>`.
     """
 
 
@@ -998,7 +998,7 @@ class StopIteration(Exception):
     Raised by built-in function :meth:`next` and an iterator’s ``__next__()``
     method to signal that there are no further items produced by the iterator.
 
-    .. tip:: Generator functions should return instead of raising this directly.
+    Generator functions should return instead of raising this directly.
     """
 
 
@@ -1023,8 +1023,8 @@ class TypeError(Exception):
 class ValueError(Exception):
     """
     Raised when an operation or function receives an argument that has the right
-    type but an inappropriate value, and the situation is not described by a more
-    precise exception such as :class:`IndexError`.
+    type but an inappropriate value. This is used when the situation is
+    not described by a more precise exception such as :class:`IndexError`.
     """