Apply suggestions from code review

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: pablogsal

peps/pep-0799.rst

@@ -1,28 +1,29 @@
 PEP: 795
-Title: A dedicated ``profilers`` module for organizing python profiling tools
+Title: A dedicated ``profilers`` package for organizing Python profiling tools
 Author: Pablo Galindo <pablogsal@python.org>,
-        László Kiss Kollár <kiss.kollar.laszlo@gmail.com>
+        László Kiss Kollár <kiss.kollar.laszlo@gmail.com>,
+Discussions-To: Pending
 Status: Draft
 Type: Standards Track
-Created: 17-Jul-2025
+Created: 21-Jul-2025
 Python-Version: 3.15
 Post-History:
 
 Abstract
 ========
 
 This PEP proposes the creation of a new standard library module named
-``profilers`` to organize Python's built-in profiling tools under a single,
+:mod:`!profilers` to organize Python's built-in profiling tools under a single,
 coherent namespace.
 
-The ``profilers`` module will provide:
+The :mod:`!profilers` module will provide:
 
-- ``profilers.tracing`` – an alias for ``cProfile``, the standard deterministic profiler
-- ``profilers.sampling`` – the new sampling profiler introduced in Python 3.15,
-  currently exposed as ``profile.sample`` (see below)
-- ``profilers.tachyon`` – an additional alias for ``profilers.sampling`` to improve discoverability
+- :mod:`!profilers.tracing` – an alias for :mod:`cProfile`, the standard deterministic profiler
+- :mod:`!profilers.sampling` – the new sampling profiler introduced in Python 3.15,
+  currently exposed as :mod:`!profile.sample` (see below)
+- :mod:`!profilers.tachyon` – an additional alias for :mod:`!profilers.sampling` to improve discoverability
 
-This PEP also proposes the deprecation of the ``profile`` module, a legacy pure-Python tracing profiler.
+This PEP also proposes the deprecation of the :mod:`profile` module, a legacy pure-Python tracing profiler.
 
 Motivation
 ==========
@@ -61,7 +62,7 @@ introducing the ``profilers`` module, users will have a well-defined and
 intuitive location to explore and access profiling functionality.
 
 Second, the proposal enhances **clarity** by naming the submodules according to
-their underlying methodology—``profilers.tracing`` for deterministic tracing
+their underlying methodology -- ``profilers.tracing`` for deterministic tracing
 profilers and ``profilers.sampling`` for statistical sampling profilers. This
 explicit categorization makes it easier to understand the behavior and
 limitations of each tool and aligns the API with the mental model users are
@@ -76,10 +77,9 @@ whether it involves low-overhead sampling or detailed tracing.
 
 Finally, this structure promotes **extensibility**. By consolidating profiling
 tools under a unified namespace, it becomes straightforward to introduce future
-profiling capabilities—such as memory profilers, I/O profilers, or hybrid
-tools—without overloading unrelated modules or adding redundant top-level names.
-The ``profilers`` module provides a natural home for the continued evolution of
-Pytho
+profiling capabilities -- such as memory profilers, I/O profilers, or hybrid
+tools -- without overloading unrelated modules or adding redundant top-level names.
+The ``profilers`` module provides a natural home for this.
 
 Specification
 =============
@@ -96,7 +96,7 @@ This PEP introduces a new ``profilers`` module containing:
 Deprecation of ``profile``
 --------------------------
 
-The ``profile`` module will be deprecated starting in Python 3.16.
+The ``profile`` module will be deprecated starting in Python 3.15.
 
 - In Python 3.15:
   - Importing ``profile`` emits a ``DeprecationWarning``.
@@ -105,20 +105,18 @@ The ``profile`` module will be deprecated starting in Python 3.16.
 - In Python 3.17:
   - The module may be removed pending community feedback and migration metrics.
 
-Users will be encouraged to use ``profilers.tracing`` instead of ``profile``, and
-``profilers.sampling`` instead of ``profile.sample``.
+From Python 3.15, :mod:`!profilers.tracing` will be preferred to :mod:`!cProfile` & :mod:`!profile`.
+The new :mod:`!profilers.sampling` module will only exist in the :mod:`profilers` package.
 
 Documentation
 =============
 
-The official Python documentation will reflect the new ``profilers`` module as the canonical
-entry point for profiling functionality. It will describe:
-
-- The distinction between tracing and sampling profilers.
-- Guidance on when each is appropriate.
+The Python documentation will use the new :mod:`!profilers` module as the canonical
+entry point for profiling functionality. It will also describe the distinction between
+tracing and sampling profilers, and include guidance on when each type is most appropriate.
 
 Documentation for ``cProfile`` and ``profile.sample`` will remain available but will link to
-the new ``profilers`` equivalents. 
+the new ``profilers`` equivalents.
 
 Backwards Compatibility
 =======================