Auto merge of #10857 - MarcusGrass:update-configuration-file-doc, r=flip1995

Explain which paths clippy searches for configuration in docs

Fixes https://github.com/rust-lang/rust-clippy/issues/9921.

Adds information on where to place the configuration files, it may be a bit verbose. Also added a comment to the section of the code where the search happens, to hopefully prevent changing that without updating the docs.

changelog: Make documentation about where to place configuration files clearer.

3 files changed, 17 insertions, 5 deletions

diff --git a/book/src/configuration.md b/book/src/configuration.md
index 1304f6a8c2f..e8274bc4575 100644
--- a/book/src/configuration.md
+++ b/book/src/configuration.md
@@ -2,8 +2,14 @@
 
 > **Note:** The configuration file is unstable and may be deprecated in the future.
 
-Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a
-basic `variable = value` mapping e.g.
+Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`, which is searched for in:
+
+1. The directory specified by the `CLIPPY_CONF_DIR` environment variable, or
+2. The directory specified by the
+[CARGO_MANIFEST_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html) environment variable, or
+3. The current directory.
+
+It contains a basic `variable = value` mapping e.g.
 
 ```toml
 avoid-breaking-exported-api = false
diff --git a/book/src/development/adding_lints.md b/book/src/development/adding_lints.md
index ccae8d37420..c26aa883eba 100644
--- a/book/src/development/adding_lints.md
+++ b/book/src/development/adding_lints.md
@@ -630,8 +630,14 @@ Before submitting your PR make sure you followed all the basic requirements:
 
 ## Adding configuration to a lint
 
-Clippy supports the configuration of lints values using a `clippy.toml` file in
-the workspace directory. Adding a configuration to a lint can be useful for
+Clippy supports the configuration of lints values using a `clippy.toml` file which is searched for in:
+
+1. The directory specified by the `CLIPPY_CONF_DIR` environment variable, or
+2. The directory specified by the
+[CARGO_MANIFEST_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html) environment variable, or
+3. The current directory.
+
+Adding a configuration to a lint can be useful for
 thresholds or to constrain some behavior that can be seen as a false positive
 for some users. Adding a configuration is done in the following steps:
 
diff --git a/clippy_lints/src/utils/conf.rs b/clippy_lints/src/utils/conf.rs
index f6de66bb514..4acff7fd322 100644
--- a/clippy_lints/src/utils/conf.rs
+++ b/clippy_lints/src/utils/conf.rs
@@ -486,7 +486,7 @@ pub fn lookup_conf_file() -> io::Result<(Option<PathBuf>, Vec<String>)> {
     const CONFIG_FILE_NAMES: [&str; 2] = [".clippy.toml", "clippy.toml"];
 
     // Start looking for a config file in CLIPPY_CONF_DIR, or failing that, CARGO_MANIFEST_DIR.
-    // If neither of those exist, use ".".
+    // If neither of those exist, use ".". (Update documentation if this priority changes)
     let mut current = env::var_os("CLIPPY_CONF_DIR")
         .or_else(|| env::var_os("CARGO_MANIFEST_DIR"))
         .map_or_else(|| PathBuf::from("."), PathBuf::from)