gh-109184: update traceback module doc w.r.t notes (message is no longer always at...

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 3eb77fc3df57099e90b46957848812d026476649..67ee73d4b2e1e53949fdd99b3883ab630bab6ac0 100644 (file)
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -139,11 +139,11 @@ The module defines the following functions:
 
    Format the exception part of a traceback using an exception value such as
    given by ``sys.last_value``.  The return value is a list of strings, each
-   ending in a newline.  Normally, the list contains a single string; however,
-   for :exc:`SyntaxError` exceptions, it contains several lines that (when
-   printed) display detailed information about where the syntax error occurred.
-   The message indicating which exception occurred is the always last string in
-   the list.
+   ending in a newline.  The list contains the exception's message, which is
+   normally a single string; however, for :exc:`SyntaxError` exceptions, it
+   contains several lines that (when printed) display detailed information
+   about where the syntax error occurred. Following the message, the list
+   contains the exception's :attr:`notes <BaseException.__notes__>`.
 
    Since Python 3.10, instead of passing *value*, an exception object
    can be passed as the first argument.  If *value* is provided, the first
@@ -153,6 +153,9 @@ The module defines the following functions:
       The *etype* parameter has been renamed to *exc* and is now
       positional-only.
 
+   .. versionchanged:: 3.11
+      The returned list now includes any notes attached to the exception.
+
 
 .. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
 
@@ -235,6 +238,12 @@ capture data for later printing in a lightweight fashion.
    group's exceptions array. The formatted output is truncated when either
    limit is exceeded.
 
+   .. versionchanged:: 3.10
+      Added the *compact* parameter.
+
+   .. versionchanged:: 3.11
+      Added the *max_group_width* and *max_group_depth* parameters.
+
    .. attribute:: __cause__
 
       A :class:`TracebackException` of the original ``__cause__``.
@@ -330,35 +339,28 @@ capture data for later printing in a lightweight fashion.
       some containing internal newlines. :func:`~traceback.print_exception`
       is a wrapper around this method which just prints the lines to a file.
 
-      The message indicating which exception occurred is always the last
-      string in the output.
-
    .. method::  format_exception_only(*, show_group=False)
 
       Format the exception part of the traceback.
 
       The return value is a generator of strings, each ending in a newline.
 
-      When *show_group* is ``False``, the generator normally emits a single
-      string; however, for :exc:`SyntaxError` exceptions, it emits several
-      lines that (when printed) display detailed information about where
-      the syntax error occurred.  The message indicating which exception
-      occurred is always the last string in the output.
+      When *show_group* is ``False``, the generator emits the exception's
+      message followed by its notes (if it has any). The exception message
+      is normally a single string; however, for :exc:`SyntaxError` exceptions,
+      it consists of several lines that (when printed) display detailed
+      information about where the syntax error occurred.
 
       When *show_group* is ``True``, and the exception is an instance of
       :exc:`BaseExceptionGroup`, the nested exceptions are included as
       well, recursively, with indentation relative to their nesting depth.
 
+      .. versionchanged:: 3.11
+         The exception's notes are now included in the output.
+
       .. versionchanged:: 3.13
          Added the *show_group* parameter.
 
-   .. versionchanged:: 3.10
-      Added the *compact* parameter.
-
-   .. versionchanged:: 3.11
-      Added the *max_group_width* and *max_group_depth* parameters.
-
-
 
 :class:`StackSummary` Objects
 -----------------------------