PEP 791: address PEP review comments

peps/pep-0791.rst

@@ -38,7 +38,10 @@ subsection of the documentation return a float, but the
 documentation doesn't say so.  In the documentation for the proposed ``imath`` module the sentence "All
 return values are integers." would be accurate.  In a similar way we
 can simplify the description of the accepted arguments for functions in both the
-:external+py3.14:mod:`math` and the new module.
+new module and the :external+py3.14:mod:`math`.
+Which content, as in beginning, will be again related to work with "just
+numbers" --- that for most people with basic education means some model of real
+numbers).
 
 Apparently, the :external+py3.14:mod:`math` module can't serve as a catch-all place
 for mathematical functions since we also have the :external+py3.14:mod:`cmath` and
@@ -52,6 +55,30 @@ Currently the :external+py3.14:mod:`math` module code in the CPython is around
 comparable with the :external+py3.14:mod:`cmath` (1340LOC), which is *not* a
 simple wrapper to the ``libm``, as most functions in the
 :external+py3.14:mod:`math` module.
+And this situation tends to be worse.  When the module split `was first
+proposed
+<https://mail.python.org/archives/list/python-ideas@python.org/thread/YYJ5YJBJNCVXQWK5K3WSVNMPUSV56LOR/>`_,
+there were only two integer-related functions:
+:external+py3.14:func:`~math.factorial` and :external+py3.14:func:`~math.gcd`.
+Now there are six, :external+py3.14:func:`~math.factorial` doesn't accept
+:class:`float`'s anymore and :external+py3.14:func:`~math.gcd` changed it's
+signature.
+
+
+Rationale
+=========
+
+Why not fix the :external+py3.14:mod:`math` module documentation instead?
+Sure, we can be much more vague in the module preamble (i.e. roughly say
+that "the :external+py3.14:mod:`math` module contains some mathematical
+functions") and we can accurately describe input/output for each function.
+
+But the major issue is that current module mix different, almost non-interlaced
+application domains.  Adding more documentation will just highlight this and
+make the issue worse for end users (more stuff to read/skip).  And it will not
+fix issue with discoverability (to know in which module to find a function, and
+that it can be found at all, you need to look at all the functions in the
+module), nor with tab-completion.
 
 
 Specification
@@ -131,6 +158,10 @@ interval math or numerical integration.
 Other proposed names include ``ntheory`` (like SymPy's submodule),
 ``integermath`` and ``imaths``.
 
+As a variant, new module can be added as a submodule of the
+:external+py3.14:mod:`math`.  The main module itself will preserve "catch-all"
+role for mathematics in the stdlib.
+
 
 Module scope and possible extensions
 ------------------------------------