From 52db90eab6d0a0e3c0416ab4ba61cc4268e6f0dd Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Fri, 22 Mar 2024 16:29:47 -0400
Subject: [PATCH] docs: clarify how multiple config files are consulted

---
 doc/config.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/config.rst b/doc/config.rst
index 4485145c0..48bd74ee3 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -37,11 +37,10 @@ A different location for the configuration file can be specified with the
 ``--rcfile=FILE`` command line option or with the ``COVERAGE_RCFILE``
 environment variable.
 
-Coverage.py will read settings from other usual configuration files if no other
-configuration file is used.  It will automatically read from "setup.cfg" or
-"tox.ini" if they exist.  In this case, the section names have "coverage:"
-prefixed, so the ``[run]`` options described below will be found in the
-``[coverage:run]`` section of the file.
+If ``.coveragerc`` doesn't exist and another file hasn't been specified, then
+coverage.py will look for settings in other common configuration files, in this
+order: setup.cfg, tox.ini, or pyproject.toml.  The first file found with
+coverage.py settings will be used and other files won't be consulted.
 
 Coverage.py will read from "pyproject.toml" if TOML support is available,
 either because you are running on Python 3.11 or later, or because you
@@ -68,6 +67,10 @@ values on multiple lines.
 Boolean values can be specified as ``on``, ``off``, ``true``, ``false``, ``1``,
 or ``0`` and are case-insensitive.
 
+In setup.cfg or tox.ini, the section names have "coverage:" prefixed, so the
+``[run]`` options described below will be found in the ``[coverage:run]``
+section of the file.
+
 TOML Syntax
 ...........