Auto merge of rust-lang#8944 - xFrednet:8877-append-doc-idents, r=Manishearth

List configuration values can now be extended instead of replaced

I've seen some `clippy.toml` files, that have a few additions to the default list of a configuration and then a copy of our default. The list will therefore not be updated, when we add new names. This change should make it simple for new users to append values instead of replacing them.

I'm uncertain if the documentation of the `".."` is apparent. Any suggestions are welcome. I've also check that the lint list displays the examples correctly.

<details>
<summary>Lint list screenshots</summary>

![image](https://user-images.githubusercontent.com/17087237/171999434-393f2f83-09aa-4bab-8b05-bd4973150f27.png)

![image](https://user-images.githubusercontent.com/17087237/171999401-e6942b53-25e6-4b09-89e5-d867c7463156.png)

</details>

---

changelog: enhancement: [`doc_markdown`]: Users can now indicate, that the `doc-valid-idents` should extend the default and not replace it
changelog: enhancement: [`blacklisted-name`]: Users can now indicate, that the `blacklisted-names` should extend the default and not replace it

Closes: rust-lang#8877

That's it. Have a fantastic weekend to everyone reading this. Here is a cookie 🍪

Author: bors

clippy_lints/src/utils/conf.rs

@@ -9,6 +9,29 @@ use std::path::{Path, PathBuf};
 use std::str::FromStr;
 use std::{cmp, env, fmt, fs, io, iter};
 
+#[rustfmt::skip]
+const DEFAULT_DOC_VALID_IDENTS: &[&str] = &[
+    "KiB", "MiB", "GiB", "TiB", "PiB", "EiB",
+    "DirectX",
+    "ECMAScript",
+    "GPLv2", "GPLv3",
+    "GitHub", "GitLab",
+    "IPv4", "IPv6",
+    "ClojureScript", "CoffeeScript", "JavaScript", "PureScript", "TypeScript",
+    "NaN", "NaNs",
+    "OAuth", "GraphQL",
+    "OCaml",
+    "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenDNS",
+    "WebGL",
+    "TensorFlow",
+    "TrueType",
+    "iOS", "macOS", "FreeBSD",
+    "TeX", "LaTeX", "BibTeX", "BibLaTeX",
+    "MinGW",
+    "CamelCase",
+];
+const DEFAULT_BLACKLISTED_NAMES: &[&str] = &["foo", "baz", "quux"];
+
 /// Holds information used by `MISSING_ENFORCED_IMPORT_RENAMES` lint.
 #[derive(Clone, Debug, Deserialize)]
 pub struct Rename {
@@ -178,8 +201,10 @@ define_Conf! {
     (msrv: Option<String> = None),
     /// Lint: BLACKLISTED_NAME.
     ///
-    /// The list of blacklisted names to lint about. NB: `bar` is not here since it has legitimate uses
-    (blacklisted_names: Vec<String> = ["foo", "baz", "quux"].iter().map(ToString::to_string).collect()),
+    /// The list of blacklisted names to lint about. NB: `bar` is not here since it has legitimate uses. The value
+    /// `".."` can be used as part of the list to indicate, that the configured values should be appended to the
+    /// default configuration of Clippy. By default any configuraction will replace the default value.
+    (blacklisted_names: Vec<String> = super::DEFAULT_BLACKLISTED_NAMES.iter().map(ToString::to_string).collect()),
     /// Lint: COGNITIVE_COMPLEXITY.
     ///
     /// The maximum cognitive complexity a function can have
@@ -191,27 +216,14 @@ define_Conf! {
     (cyclomatic_complexity_threshold: Option<u64> = None),
     /// Lint: DOC_MARKDOWN.
     ///
-    /// The list of words this lint should not consider as identifiers needing ticks
-    (doc_valid_idents: Vec<String> = [
-        "KiB", "MiB", "GiB", "TiB", "PiB", "EiB",
-        "DirectX",
-        "ECMAScript",
-        "GPLv2", "GPLv3",
-        "GitHub", "GitLab",
-        "IPv4", "IPv6",
-        "ClojureScript", "CoffeeScript", "JavaScript", "PureScript", "TypeScript",
-        "NaN", "NaNs",
-        "OAuth", "GraphQL",
-        "OCaml",
-        "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenDNS",
-        "WebGL",
-        "TensorFlow",
-        "TrueType",
-        "iOS", "macOS", "FreeBSD",
-        "TeX", "LaTeX", "BibTeX", "BibLaTeX",
-        "MinGW",
-        "CamelCase",
-    ].iter().map(ToString::to_string).collect()),
+    /// The list of words this lint should not consider as identifiers needing ticks. The value
+    /// `".."` can be used as part of the list to indicate, that the configured values should be appended to the
+    /// default configuration of Clippy. By default any configuraction will replace the default value. For example:
+    /// * `doc-valid-idents = ["ClipPy"]` would replace the default list with `["ClipPy"]`.
+    /// * `doc-valid-idents = ["ClipPy", ".."]` would append `ClipPy` to the default list.
+    ///
+    /// Default list:
+    (doc_valid_idents: Vec<String> = super::DEFAULT_DOC_VALID_IDENTS.iter().map(ToString::to_string).collect()),
     /// Lint: TOO_MANY_ARGUMENTS.
     ///
     /// The maximum number of argument a function or method can have
@@ -401,7 +413,21 @@ pub fn read(path: &Path) -> TryConf {
         Err(e) => return TryConf::from_error(e),
         Ok(content) => content,
     };
-    toml::from_str(&content).unwrap_or_else(TryConf::from_error)
+    match toml::from_str::<TryConf>(&content) {
+        Ok(mut conf) => {
+            extend_vec_if_indicator_present(&mut conf.conf.doc_valid_idents, DEFAULT_DOC_VALID_IDENTS);
+            extend_vec_if_indicator_present(&mut conf.conf.blacklisted_names, DEFAULT_BLACKLISTED_NAMES);
+
+            conf
+        },
+        Err(e) => TryConf::from_error(e),
+    }
+}
+
+fn extend_vec_if_indicator_present(vec: &mut Vec<String>, default: &[&str]) {
+    if vec.contains(&"..".to_string()) {
+        vec.extend(default.iter().map(ToString::to_string));
+    }
 }
 
 const SEPARATOR_WIDTH: usize = 4;

tests/ui-toml/blacklisted_names_append/blacklisted_names.rs

@@ -0,0 +1,10 @@
+#[warn(clippy::blacklisted_name)]
+
+fn main() {
+    // `foo` is part of the default configuration
+    let foo = "bar";
+    // `ducks` was unrightfully blacklisted
+    let ducks = ["quack", "quack"];
+    // `fox` is okay
+    let fox = ["what", "does", "the", "fox", "say", "?"];
+}

tests/ui-toml/blacklisted_names_append/blacklisted_names.stderr

@@ -0,0 +1,16 @@
+error: use of a blacklisted/placeholder name `foo`
+  --> $DIR/blacklisted_names.rs:5:9
+   |
+LL |     let foo = "bar";
+   |         ^^^
+   |
+   = note: `-D clippy::blacklisted-name` implied by `-D warnings`
+
+error: use of a blacklisted/placeholder name `ducks`
+  --> $DIR/blacklisted_names.rs:7:9
+   |
+LL |     let ducks = ["quack", "quack"];
+   |         ^^^^^
+
+error: aborting due to 2 previous errors
+

tests/ui-toml/blacklisted_names_append/clippy.toml

@@ -0,0 +1 @@
+blacklisted-names = ["ducks", ".."]

tests/ui-toml/blacklisted_names_replace/blacklisted_names.rs

@@ -0,0 +1,10 @@
+#[warn(clippy::blacklisted_name)]
+
+fn main() {
+    // `foo` is part of the default configuration
+    let foo = "bar";
+    // `ducks` was unrightfully blacklisted
+    let ducks = ["quack", "quack"];
+    // `fox` is okay
+    let fox = ["what", "does", "the", "fox", "say", "?"];
+}

tests/ui-toml/blacklisted_names_replace/blacklisted_names.stderr

@@ -0,0 +1,10 @@
+error: use of a blacklisted/placeholder name `ducks`
+  --> $DIR/blacklisted_names.rs:7:9
+   |
+LL |     let ducks = ["quack", "quack"];
+   |         ^^^^^
+   |
+   = note: `-D clippy::blacklisted-name` implied by `-D warnings`
+
+error: aborting due to previous error
+

tests/ui-toml/blacklisted_names_replace/clippy.toml

@@ -0,0 +1 @@
+blacklisted-names = ["ducks"]

tests/ui-toml/doc_valid_idents_append/clippy.toml

@@ -0,0 +1 @@
+doc-valid-idents = ["ClipPy", ".."]

tests/ui-toml/doc_valid_idents_append/doc_markdown.rs

@@ -0,0 +1,12 @@
+#![warn(clippy::doc_markdown)]
+
+/// This is a special interface for ClipPy which doesn't require backticks
+fn allowed_name() {}
+
+/// OAuth and LaTeX are inside Clippy's default list.
+fn default_name() {}
+
+/// TestItemThingyOfCoolness might sound cool but is not on the list and should be linted.
+fn unknown_name() {}
+
+fn main() {}

tests/ui-toml/doc_valid_idents_append/doc_markdown.stderr

@@ -0,0 +1,14 @@
+error: item in documentation is missing backticks
+  --> $DIR/doc_markdown.rs:9:5
+   |
+LL | /// TestItemThingyOfCoolness might sound cool but is not on the list and should be linted.
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = note: `-D clippy::doc-markdown` implied by `-D warnings`
+help: try
+   |
+LL | /// `TestItemThingyOfCoolness` might sound cool but is not on the list and should be linted.
+   |     ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: aborting due to previous error
+