Rollup merge of rust-lang#56689 - QuietMisdreavus:rustdoc-lint-group, r=pnkfelix

add a lint group for lints emitted by rustdoc

As rustdoc adds more lints that it specifically manages, it would be nice to be able to lump them all together. This gives us a new group just for that.

I deliberately didn't include `missing_docs` because this is kind of a stepping stone for moving our lints into tool lints (i.e. `#![warn(rustdoc::private_doc_tests)]`), since all of these are specifically emitted by rustdoc. If we want to move `missing_docs` out of the compiler, that's also an option, but it would create a surprising change of behavior.

I also took the chance to rewrite the lint descriptions of these lints to better match the style of the other lints. `>_>`

Author: pietroalbini

src/librustc/lint/builtin.rs

@@ -315,19 +315,19 @@ declare_lint! {
 declare_lint! {
     pub INTRA_DOC_LINK_RESOLUTION_FAILURE,
     Warn,
-    "warn about documentation intra links resolution failure"
+    "failures in resolving intra-doc link targets"
 }
 
 declare_lint! {
     pub MISSING_DOC_CODE_EXAMPLES,
     Allow,
-    "warn about missing code example in an item's documentation"
+    "detects publicly-exported items without code samples in their documentation"
 }
 
 declare_lint! {
     pub PRIVATE_DOC_TESTS,
     Allow,
-    "warn about doc test in private item"
+    "detects code samples in docs of private items not documented by rustdoc"
 }
 
 declare_lint! {

src/librustc_lint/lib.rs

@@ -53,6 +53,9 @@ use rustc::lint::builtin::{
     ABSOLUTE_PATHS_NOT_STARTING_WITH_CRATE,
     ELIDED_LIFETIMES_IN_PATHS,
     EXPLICIT_OUTLIVES_REQUIREMENTS,
+    INTRA_DOC_LINK_RESOLUTION_FAILURE,
+    MISSING_DOC_CODE_EXAMPLES,
+    PRIVATE_DOC_TESTS,
     parser::QUESTION_MARK_MACRO_SEP
 };
 use rustc::session;
@@ -204,6 +207,12 @@ pub fn register_builtins(store: &mut lint::LintStore, sess: Option<&Session>) {
                     // MACRO_USE_EXTERN_CRATE,
                     );
 
+    add_lint_group!(sess,
+                    "rustdoc",
+                    INTRA_DOC_LINK_RESOLUTION_FAILURE,
+                    MISSING_DOC_CODE_EXAMPLES,
+                    PRIVATE_DOC_TESTS);
+
     // Guidelines for creating a future incompatibility lint:
     //
     // - Create a lint defaulting to warn as normal, with ideally the same error

src/test/rustdoc-ui/lint-group.rs

@@ -0,0 +1,34 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Documenting the kinds of lints emitted by rustdoc.
+//!
+//! ```
+//! println!("sup");
+//! ```
+
+#![deny(rustdoc)]
+
+/// what up, let's make an [error]
+///
+/// ```
+/// println!("sup");
+/// ```
+pub fn link_error() {} //~^^^^^ ERROR cannot be resolved, ignoring it
+
+/// wait, this doesn't have a doctest?
+pub fn no_doctest() {} //~^ ERROR Missing code example in this documentation
+
+/// wait, this *does* have a doctest?
+///
+/// ```
+/// println!("sup");
+/// ```
+fn private_doctest() {} //~^^^^^ ERROR Documentation test in private item

src/test/rustdoc-ui/lint-group.stderr

@@ -0,0 +1,44 @@
+error: Documentation test in private item
+  --> $DIR/lint-group.rs:29:1
+   |
+LL | / /// wait, this *does* have a doctest?
+LL | | ///
+LL | | /// ```
+LL | | /// println!("sup");
+LL | | /// ```
+   | |_______^
+   |
+note: lint level defined here
+  --> $DIR/lint-group.rs:17:9
+   |
+LL | #![deny(rustdoc)]
+   |         ^^^^^^^
+   = note: #[deny(private_doc_tests)] implied by #[deny(rustdoc)]
+
+error: `[error]` cannot be resolved, ignoring it...
+  --> $DIR/lint-group.rs:19:29
+   |
+LL | /// what up, let's make an [error]
+   |                             ^^^^^ cannot be resolved, ignoring
+   |
+note: lint level defined here
+  --> $DIR/lint-group.rs:17:9
+   |
+LL | #![deny(rustdoc)]
+   |         ^^^^^^^
+   = note: #[deny(intra_doc_link_resolution_failure)] implied by #[deny(rustdoc)]
+   = help: to escape `[` and `]` characters, just add '/' before them like `/[` or `/]`
+
+error: Missing code example in this documentation
+  --> $DIR/lint-group.rs:26:1
+   |
+LL | /// wait, this doesn't have a doctest?
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+note: lint level defined here
+  --> $DIR/lint-group.rs:17:9
+   |
+LL | #![deny(rustdoc)]
+   |         ^^^^^^^
+   = note: #[deny(missing_doc_code_examples)] implied by #[deny(rustdoc)]
+