8 files changed, 69 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b62c9a59aa..9d698c7c472 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6435,6 +6435,7 @@ Released 2018-09-13
 [`max-suggested-slice-pattern-length`]: https://doc.rust-lang.org/clippy/lint_configuration.html#max-suggested-slice-pattern-length
 [`max-trait-bounds`]: https://doc.rust-lang.org/clippy/lint_configuration.html#max-trait-bounds
 [`min-ident-chars-threshold`]: https://doc.rust-lang.org/clippy/lint_configuration.html#min-ident-chars-threshold
+[`missing-docs-allow-unused`]: https://doc.rust-lang.org/clippy/lint_configuration.html#missing-docs-allow-unused
 [`missing-docs-in-crate-items`]: https://doc.rust-lang.org/clippy/lint_configuration.html#missing-docs-in-crate-items
 [`module-item-order-groupings`]: https://doc.rust-lang.org/clippy/lint_configuration.html#module-item-order-groupings
 [`module-items-ordered-within-groupings`]: https://doc.rust-lang.org/clippy/lint_configuration.html#module-items-ordered-within-groupings
diff --git a/book/src/lint_configuration.md b/book/src/lint_configuration.md
index 2314d1beac7..cc8e362e836 100644
--- a/book/src/lint_configuration.md
+++ b/book/src/lint_configuration.md
@@ -734,6 +734,16 @@ Minimum chars an ident can have, anything below or equal to this will be linted.
 * [`min_ident_chars`](https://rust-lang.github.io/rust-clippy/master/index.html#min_ident_chars)
 
 
+## `missing-docs-allow-unused`
+Whether to allow fields starting with underscore to skip documentation requirements
+
+**Default Value:** `false`
+
+---
+**Affected lints:**
+* [`missing_docs_in_private_items`](https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items)
+
+
 ## `missing-docs-in-crate-items`
 Whether to **only** check for missing documentation in items visible within the current
 crate. For example, `pub(crate)` items.
diff --git a/clippy_config/src/conf.rs b/clippy_config/src/conf.rs
index 511cb84527d..c1a561aa407 100644
--- a/clippy_config/src/conf.rs
+++ b/clippy_config/src/conf.rs
@@ -675,6 +675,9 @@ define_Conf! {
     /// Minimum chars an ident can have, anything below or equal to this will be linted.
     #[lints(min_ident_chars)]
     min_ident_chars_threshold: u64 = 1,
+    /// Whether to allow fields starting with underscore to skip documentation requirements
+    #[lints(missing_docs_in_private_items)]
+    missing_docs_allow_unused: bool = false,
     /// Whether to **only** check for missing documentation in items visible within the current
     /// crate. For example, `pub(crate)` items.
     #[lints(missing_docs_in_private_items)]
diff --git a/clippy_lints/src/missing_doc.rs b/clippy_lints/src/missing_doc.rs
index b234b190153..3ac9adfa4f3 100644
--- a/clippy_lints/src/missing_doc.rs
+++ b/clippy_lints/src/missing_doc.rs
@@ -48,6 +48,8 @@ pub struct MissingDoc {
     /// Whether to **only** check for missing documentation in items visible within the current
     /// crate. For example, `pub(crate)` items.
     crate_items_only: bool,
+    /// Whether to allow fields starting with underscore to skip documentation requirements
+    allow_unused: bool,
     /// Stack of whether #[doc(hidden)] is set
     /// at each level which has lint attributes.
     doc_hidden_stack: Vec<bool>,
@@ -59,6 +61,7 @@ impl MissingDoc {
     pub fn new(conf: &'static Conf) -> Self {
         Self {
             crate_items_only: conf.missing_docs_in_crate_items,
+            allow_unused: conf.missing_docs_allow_unused,
             doc_hidden_stack: vec![false],
             prev_span: None,
         }
@@ -88,6 +91,14 @@ impl MissingDoc {
         article: &'static str,
         desc: &'static str,
     ) {
+        // Skip checking if the item starts with underscore and allow_unused is enabled
+        if self.allow_unused {
+            if let Some(name) = cx.tcx.opt_item_name(def_id.to_def_id()) {
+                if name.as_str().starts_with('_') {
+                    return;
+                }
+            }
+        }
         // If we're building a test harness, then warning about
         // documentation is probably not really relevant right now.
         if cx.sess().opts.test {
diff --git a/tests/ui-toml/missing_docs_allow_unused/clippy.toml b/tests/ui-toml/missing_docs_allow_unused/clippy.toml
new file mode 100644
index 00000000000..2fe64b2755b
--- /dev/null
+++ b/tests/ui-toml/missing_docs_allow_unused/clippy.toml
@@ -0,0 +1 @@
+missing-docs-allow-unused = true
diff --git a/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.rs b/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.rs
new file mode 100644
index 00000000000..bda3fbc928b
--- /dev/null
+++ b/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.rs
@@ -0,0 +1,19 @@
+//! Test file for missing_docs_in_private_items lint with allow_unused configuration
+#![warn(clippy::missing_docs_in_private_items)]
+#![allow(dead_code)]
+
+/// A struct with some documented and undocumented fields
+struct Test {
+    /// This field is documented
+    field1: i32,
+    _unused: i32, // This should not trigger a warning because it starts with underscore
+    field3: i32,  //~ missing_docs_in_private_items
+}
+
+struct Test2 {
+    //~^ missing_docs_in_private_items
+    _field1: i32, // This should not trigger a warning
+    _field2: i32, // This should not trigger a warning
+}
+
+fn main() {}
diff --git a/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.stderr b/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.stderr
new file mode 100644
index 00000000000..59b22cd47d4
--- /dev/null
+++ b/tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.stderr
@@ -0,0 +1,21 @@
+error: missing documentation for a struct field
+  --> tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.rs:10:5
+   |
+LL |     field3: i32,
+   |     ^^^^^^^^^^^
+   |
+   = note: `-D clippy::missing-docs-in-private-items` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::missing_docs_in_private_items)]`
+
+error: missing documentation for a struct
+  --> tests/ui-toml/missing_docs_allow_unused/missing_docs_allow_unused.rs:13:1
+   |
+LL | / struct Test2 {
+LL | |
+LL | |     _field1: i32, // This should not trigger a warning
+LL | |     _field2: i32, // This should not trigger a warning
+LL | | }
+   | |_^
+
+error: aborting due to 2 previous errors
+
diff --git a/tests/ui-toml/toml_unknown_key/conf_unknown_key.stderr b/tests/ui-toml/toml_unknown_key/conf_unknown_key.stderr
index f2eaa66a4ae..0a36cd3cf26 100644
--- a/tests/ui-toml/toml_unknown_key/conf_unknown_key.stderr
+++ b/tests/ui-toml/toml_unknown_key/conf_unknown_key.stderr
@@ -57,6 +57,7 @@ error: error reading Clippy's configuration file: unknown field `foobar`, expect
            max-suggested-slice-pattern-length
            max-trait-bounds
            min-ident-chars-threshold
+           missing-docs-allow-unused
            missing-docs-in-crate-items
            module-item-order-groupings
            module-items-ordered-within-groupings
@@ -149,6 +150,7 @@ error: error reading Clippy's configuration file: unknown field `barfoo`, expect
            max-suggested-slice-pattern-length
            max-trait-bounds
            min-ident-chars-threshold
+           missing-docs-allow-unused
            missing-docs-in-crate-items
            module-item-order-groupings
            module-items-ordered-within-groupings
@@ -241,6 +243,7 @@ error: error reading Clippy's configuration file: unknown field `allow_mixed_uni
            max-suggested-slice-pattern-length
            max-trait-bounds
            min-ident-chars-threshold
+           missing-docs-allow-unused
            missing-docs-in-crate-items
            module-item-order-groupings
            module-items-ordered-within-groupings