From 6add6a1e1e5681d8d80f48326795b734c7966518 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 12 Sep 2022 15:02:45 +0200 Subject: [PATCH 1/7] Change default lint level of INVALID_HTML_TAGS to warning --- src/librustdoc/lint.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustdoc/lint.rs b/src/librustdoc/lint.rs index e76c19a61c541..3aad97bc296fb 100644 --- a/src/librustdoc/lint.rs +++ b/src/librustdoc/lint.rs @@ -148,7 +148,7 @@ declare_rustdoc_lint! { /// /// [rustdoc book]: ../../../rustdoc/lints.html#invalid_html_tags INVALID_HTML_TAGS, - Allow, + Warn, "detects invalid HTML tags in doc comments" } From c23ed655eb1244cf0fb5d51d7bdb4e473b540e15 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 13 Sep 2022 12:01:07 +0200 Subject: [PATCH 2/7] Update rustdoc tests --- .../intra-doc/malformed-generics.rs | 9 ++ .../intra-doc/malformed-generics.stderr | 82 ++++++++++++++++--- .../extern-crate-only-used-in-link.rs | 2 +- 3 files changed, 79 insertions(+), 14 deletions(-) diff --git a/src/test/rustdoc-ui/intra-doc/malformed-generics.rs b/src/test/rustdoc-ui/intra-doc/malformed-generics.rs index 15e02925ed90d..161625ed28c29 100644 --- a/src/test/rustdoc-ui/intra-doc/malformed-generics.rs +++ b/src/test/rustdoc-ui/intra-doc/malformed-generics.rs @@ -3,17 +3,26 @@ //! [Vec<] //~ ERROR //! [Vec] //~ ERROR +//~^ WARN //! [Vec>>] //~ ERROR +//~^ WARN //! [Vec>>] //~ ERROR +//~^ WARN //! [] //~ ERROR +//~^ WARN //! [] //~ ERROR +//~^ WARN //! [Vec::new()] //~ ERROR +//~^ WARN //! [Vec<>] //~ ERROR +//~^ WARN //! [Vec<>] //~ ERROR //! [Vec<<>>] //~ ERROR // FIXME(#74563) support UFCS //! [::into_iter] //~ ERROR +//~^ WARN //! [ as IntoIterator>::iter] //~ ERROR +//~^ WARN diff --git a/src/test/rustdoc-ui/intra-doc/malformed-generics.stderr b/src/test/rustdoc-ui/intra-doc/malformed-generics.stderr index 5bc0f84e24d13..08349fef88d38 100644 --- a/src/test/rustdoc-ui/intra-doc/malformed-generics.stderr +++ b/src/test/rustdoc-ui/intra-doc/malformed-generics.stderr @@ -23,67 +23,67 @@ LL | //! [Vec] | ^^^^^^^^^^ unbalanced angle brackets error: unresolved link to `Vec>>` - --> $DIR/malformed-generics.rs:6:6 + --> $DIR/malformed-generics.rs:7:6 | LL | //! [Vec>>] | ^^^^^^^^^^^^ unbalanced angle brackets error: unresolved link to `Vec>>` - --> $DIR/malformed-generics.rs:7:6 + --> $DIR/malformed-generics.rs:9:6 | LL | //! [Vec>>] | ^^^^^^^^ unbalanced angle brackets error: unresolved link to ` $DIR/malformed-generics.rs:8:6 + --> $DIR/malformed-generics.rs:11:6 | LL | //! [ $DIR/malformed-generics.rs:9:6 + --> $DIR/malformed-generics.rs:12:6 | LL | //! [Vec::<] | ^^^^^^ unbalanced angle brackets error: unresolved link to `` - --> $DIR/malformed-generics.rs:10:6 + --> $DIR/malformed-generics.rs:13:6 | LL | //! [] | ^^^ missing type for generic parameters error: unresolved link to `` - --> $DIR/malformed-generics.rs:11:6 + --> $DIR/malformed-generics.rs:15:6 | LL | //! [] | ^^^^^^^^^^^^^^^^ missing type for generic parameters error: unresolved link to `Vec::new` - --> $DIR/malformed-generics.rs:12:6 + --> $DIR/malformed-generics.rs:17:6 | LL | //! [Vec::new()] | ^^^^^^^^^^^^^ has invalid path separator error: unresolved link to `Vec<>` - --> $DIR/malformed-generics.rs:13:6 + --> $DIR/malformed-generics.rs:19:6 | LL | //! [Vec<>] | ^^^^^^^^ too many angle brackets error: unresolved link to `Vec<>` - --> $DIR/malformed-generics.rs:14:6 + --> $DIR/malformed-generics.rs:21:6 | LL | //! [Vec<>] | ^^^^^ empty angle brackets error: unresolved link to `Vec<<>>` - --> $DIR/malformed-generics.rs:15:6 + --> $DIR/malformed-generics.rs:22:6 | LL | //! [Vec<<>>] | ^^^^^^^ too many angle brackets error: unresolved link to `::into_iter` - --> $DIR/malformed-generics.rs:18:6 + --> $DIR/malformed-generics.rs:25:6 | LL | //! [::into_iter] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fully-qualified syntax is unsupported @@ -91,12 +91,68 @@ LL | //! [::into_iter] = note: see https://github.com/rust-lang/rust/issues/74563 for more information error: unresolved link to ` as IntoIterator>::iter` - --> $DIR/malformed-generics.rs:19:6 + --> $DIR/malformed-generics.rs:27:6 | LL | //! [ as IntoIterator>::iter] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fully-qualified syntax is unsupported | = note: see https://github.com/rust-lang/rust/issues/74563 for more information -error: aborting due to 15 previous errors +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:5:13 + | +LL | //! [Vec] + | ^^^ + | + = note: `#[warn(rustdoc::invalid_html_tags)]` on by default + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:7:13 + | +LL | //! [Vec>>] + | ^^^ + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:9:9 + | +LL | //! [Vec>>] + | ^^^ + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:13:6 + | +LL | //! [] + | ^^^ + +warning: unclosed HTML tag `invalid` + --> $DIR/malformed-generics.rs:15:6 + | +LL | //! [] + | ^^^^^^^^ + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:17:10 + | +LL | //! [Vec::new()] + | ^^^ + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:19:10 + | +LL | //! [Vec<>] + | ^^^ + +warning: unclosed HTML tag `Vec` + --> $DIR/malformed-generics.rs:25:6 + | +LL | //! [::into_iter] + | ^^^^ + +warning: unclosed HTML tag `T` + --> $DIR/malformed-generics.rs:27:10 + | +LL | //! [ as IntoIterator>::iter] + | ^^^ + +error: aborting due to 15 previous errors; 9 warnings emitted diff --git a/src/test/rustdoc/intra-doc/extern-crate-only-used-in-link.rs b/src/test/rustdoc/intra-doc/extern-crate-only-used-in-link.rs index 5d8dcf8bc1d16..ad50887e9221c 100644 --- a/src/test/rustdoc/intra-doc/extern-crate-only-used-in-link.rs +++ b/src/test/rustdoc/intra-doc/extern-crate-only-used-in-link.rs @@ -16,4 +16,4 @@ //! [`empty`] // @has - '//a[@href="../empty2/index.html"]' 'empty2' -//! [empty2] +//! [`empty2`] From d9570e0510c87d4e7ba938005e506eb5cc7fc91b Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 12 Sep 2022 12:07:43 +0200 Subject: [PATCH 3/7] Stabilize rustdoc CHECK_INVALID_HTML_TAGS check --- src/librustdoc/passes/html_tags.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/librustdoc/passes/html_tags.rs b/src/librustdoc/passes/html_tags.rs index 694b03161d929..67fc71665ccf7 100644 --- a/src/librustdoc/passes/html_tags.rs +++ b/src/librustdoc/passes/html_tags.rs @@ -22,10 +22,8 @@ struct InvalidHtmlTagsLinter<'a, 'tcx> { } pub(crate) fn check_invalid_html_tags(krate: Crate, cx: &mut DocContext<'_>) -> Crate { - if cx.tcx.sess.is_nightly_build() { - let mut coll = InvalidHtmlTagsLinter { cx }; - coll.visit_crate(&krate); - } + let mut coll = InvalidHtmlTagsLinter { cx }; + coll.visit_crate(&krate); krate } From 3416fa1882a9ea5b4d7c32b62afccbe9d01fb79a Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 8 Oct 2022 14:42:38 +0200 Subject: [PATCH 4/7] Fix doc lint error --- compiler/rustc_errors/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compiler/rustc_errors/src/lib.rs b/compiler/rustc_errors/src/lib.rs index 94a493992e593..2f6686f81965b 100644 --- a/compiler/rustc_errors/src/lib.rs +++ b/compiler/rustc_errors/src/lib.rs @@ -411,7 +411,7 @@ struct HandlerInner { /// would be unnecessary repetition. taught_diagnostics: FxHashSet, - /// Used to suggest rustc --explain + /// Used to suggest rustc --explain `` emitted_diagnostic_codes: FxIndexSet, /// This set contains a hash of every diagnostic that has been emitted by From adc24d1b5efb768a8e81ec5a26133f2351c4dd3f Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sun, 9 Oct 2022 16:15:23 +0200 Subject: [PATCH 5/7] Fix compiler docs --- compiler/rustc_hir_analysis/src/check/check.rs | 4 +++- .../src/constrained_generic_params.rs | 10 +++++++--- .../src/impl_wf_check/min_specialization.rs | 8 ++++++++ compiler/rustc_hir_analysis/src/mem_categorization.rs | 2 +- compiler/rustc_middle/src/thir.rs | 2 +- compiler/rustc_middle/src/ty/adt.rs | 4 ++-- compiler/rustc_parse/src/lib.rs | 3 ++- .../rustc_trait_selection/src/traits/auto_trait.rs | 8 ++++---- compiler/rustc_trait_selection/src/traits/project.rs | 5 +++-- .../rustc_trait_selection/src/traits/select/mod.rs | 2 +- 10 files changed, 32 insertions(+), 16 deletions(-) diff --git a/compiler/rustc_hir_analysis/src/check/check.rs b/compiler/rustc_hir_analysis/src/check/check.rs index c92d8dfb60271..77ab27266b286 100644 --- a/compiler/rustc_hir_analysis/src/check/check.rs +++ b/compiler/rustc_hir_analysis/src/check/check.rs @@ -707,10 +707,12 @@ pub(super) fn check_opaque_for_cycles<'tcx>( /// check those cases in the `param_env` of that function, which may have /// bounds not on this opaque type: /// -/// type X = impl Clone +/// ```ignore (illustrative) +/// type X = impl Clone; /// fn f(t: T) -> X { /// t /// } +/// ``` /// /// Without this check the above code is incorrectly accepted: we would ICE if /// some tried, for example, to clone an `Option>`. diff --git a/compiler/rustc_hir_analysis/src/constrained_generic_params.rs b/compiler/rustc_hir_analysis/src/constrained_generic_params.rs index 8428e46640671..213b89fc7843c 100644 --- a/compiler/rustc_hir_analysis/src/constrained_generic_params.rs +++ b/compiler/rustc_hir_analysis/src/constrained_generic_params.rs @@ -114,9 +114,9 @@ pub fn identify_constrained_generic_params<'tcx>( /// ``` /// The impl's predicates are collected from left to right. Ignoring /// the implicit `Sized` bounds, these are -/// * T: Debug -/// * U: Iterator -/// * ::Item = T -- a desugared ProjectionPredicate +/// * `T: Debug` +/// * `U: Iterator` +/// * `::Item = T` -- a desugared ProjectionPredicate /// /// When we, for example, try to go over the trait-reference /// `IntoIter as Trait`, we substitute the impl parameters with fresh @@ -132,12 +132,16 @@ pub fn identify_constrained_generic_params<'tcx>( /// /// We *do* have to be somewhat careful when projection targets contain /// projections themselves, for example in +/// +/// ```ignore (illustrative) /// impl Trait for U where /// /* 0 */ S: Iterator, /// /* - */ U: Iterator, /// /* 1 */ ::Item: ToOwned::Item)> /// /* 2 */ W: Iterator /// /* 3 */ V: Debug +/// ``` +/// /// we have to evaluate the projections in the order I wrote them: /// `V: Debug` requires `V` to be evaluated. The only projection that /// *determines* `V` is 2 (1 contains it, but *does not determine it*, diff --git a/compiler/rustc_hir_analysis/src/impl_wf_check/min_specialization.rs b/compiler/rustc_hir_analysis/src/impl_wf_check/min_specialization.rs index bfe5d4751e08f..e806e94879d93 100644 --- a/compiler/rustc_hir_analysis/src/impl_wf_check/min_specialization.rs +++ b/compiler/rustc_hir_analysis/src/impl_wf_check/min_specialization.rs @@ -130,8 +130,10 @@ fn check_always_applicable(tcx: TyCtxt<'_>, impl1_def_id: LocalDefId, impl2_node /// /// Example /// +/// ```ignore (illustrative) /// impl Foo for B { /* impl2 */ } /// impl Foo> for C { /* impl1 */ } +/// ``` /// /// Would return `S1 = [C]` and `S2 = [Vec, C]`. fn get_impl_substs<'tcx>( @@ -225,13 +227,17 @@ fn unconstrained_parent_impl_substs<'tcx>( /// /// For example forbid the following: /// +/// ```ignore (illustrative) /// impl Tr for A { } /// impl Tr for (B, B) { } +/// ``` /// /// Note that only consider the unconstrained parameters of the base impl: /// +/// ```ignore (illustrative) /// impl> Tr for I { } /// impl Tr for Vec { } +/// ``` /// /// The substs for the parent impl here are `[T, Vec]`, which repeats `T`, /// but `S` is constrained in the parent impl, so `parent_substs` is only @@ -256,8 +262,10 @@ fn check_duplicate_params<'tcx>( /// /// For example forbid the following: /// +/// ```ignore (illustrative) /// impl Tr for A { } /// impl Tr for &'static i32 { } +/// ``` fn check_static_lifetimes<'tcx>( tcx: TyCtxt<'tcx>, parent_substs: &Vec>, diff --git a/compiler/rustc_hir_analysis/src/mem_categorization.rs b/compiler/rustc_hir_analysis/src/mem_categorization.rs index a6880c7e77ac3..b62c5b5e07783 100644 --- a/compiler/rustc_hir_analysis/src/mem_categorization.rs +++ b/compiler/rustc_hir_analysis/src/mem_categorization.rs @@ -184,7 +184,7 @@ impl<'a, 'tcx> MemCategorizationContext<'a, 'tcx> { /// modes #42640) may look like `Some(x)` but in fact have /// implicit deref patterns attached (e.g., it is really /// `&Some(x)`). In that case, we return the "outermost" type - /// (e.g., `&Option). + /// (e.g., `&Option`). pub(crate) fn pat_ty_adjusted(&self, pat: &hir::Pat<'_>) -> McResult> { // Check for implicit `&` types wrapping the pattern; note // that these are never attached to binding patterns, so diff --git a/compiler/rustc_middle/src/thir.rs b/compiler/rustc_middle/src/thir.rs index 84374a25ed85e..f46f0ea4cabed 100644 --- a/compiler/rustc_middle/src/thir.rs +++ b/compiler/rustc_middle/src/thir.rs @@ -203,7 +203,7 @@ pub enum StmtKind<'tcx> { /// `let pat: ty = ` initializer: Option, - /// `let pat: ty = else { } + /// `let pat: ty = else { }` else_block: Option, /// The lint level for this `let` statement. diff --git a/compiler/rustc_middle/src/ty/adt.rs b/compiler/rustc_middle/src/ty/adt.rs index 80bbc8e630e02..26b6be7a1b891 100644 --- a/compiler/rustc_middle/src/ty/adt.rs +++ b/compiler/rustc_middle/src/ty/adt.rs @@ -332,13 +332,13 @@ impl<'tcx> AdtDef<'tcx> { self.flags().contains(AdtFlags::IS_PHANTOM_DATA) } - /// Returns `true` if this is Box. + /// Returns `true` if this is `Box`. #[inline] pub fn is_box(self) -> bool { self.flags().contains(AdtFlags::IS_BOX) } - /// Returns `true` if this is UnsafeCell. + /// Returns `true` if this is `UnsafeCell`. #[inline] pub fn is_unsafe_cell(self) -> bool { self.flags().contains(AdtFlags::IS_UNSAFE_CELL) diff --git a/compiler/rustc_parse/src/lib.rs b/compiler/rustc_parse/src/lib.rs index 0bdfe10359c0b..3dcadb4c9115f 100644 --- a/compiler/rustc_parse/src/lib.rs +++ b/compiler/rustc_parse/src/lib.rs @@ -39,7 +39,8 @@ mod errors; // uses a HOF to parse anything, and includes file and // `source_str`. -/// A variant of 'panictry!' that works on a Vec instead of a single DiagnosticBuilder. +/// A variant of 'panictry!' that works on a `Vec` instead of a single +/// `DiagnosticBuilder`. macro_rules! panictry_buffer { ($handler:expr, $e:expr) => {{ use rustc_errors::FatalError; diff --git a/compiler/rustc_trait_selection/src/traits/auto_trait.rs b/compiler/rustc_trait_selection/src/traits/auto_trait.rs index c716c4b0be905..ed34ab95ad6c0 100644 --- a/compiler/rustc_trait_selection/src/traits/auto_trait.rs +++ b/compiler/rustc_trait_selection/src/traits/auto_trait.rs @@ -66,13 +66,13 @@ impl<'tcx> AutoTraitFinder<'tcx> { /// struct Foo { data: Box } /// ``` /// - /// then this might return that Foo: Send if T: Send (encoded in the AutoTraitResult type). - /// The analysis attempts to account for custom impls as well as other complex cases. This - /// result is intended for use by rustdoc and other such consumers. + /// then this might return that `Foo: Send` if `T: Send` (encoded in the AutoTraitResult + /// type). The analysis attempts to account for custom impls as well as other complex cases. + /// This result is intended for use by rustdoc and other such consumers. /// /// (Note that due to the coinductive nature of Send, the full and correct result is actually /// quite simple to generate. That is, when a type has no custom impl, it is Send iff its field - /// types are all Send. So, in our example, we might have that Foo: Send if Box: Send. + /// types are all Send. So, in our example, we might have that `Foo: Send` if `Box: Send`. /// But this is often not the best way to present to the user.) /// /// Warning: The API should be considered highly unstable, and it may be refactored or removed diff --git a/compiler/rustc_trait_selection/src/traits/project.rs b/compiler/rustc_trait_selection/src/traits/project.rs index e1485079487cf..511646b0eaf29 100644 --- a/compiler/rustc_trait_selection/src/traits/project.rs +++ b/compiler/rustc_trait_selection/src/traits/project.rs @@ -62,7 +62,8 @@ enum ProjectionCandidate<'tcx> { /// From a where-clause in the env or object type ParamEnv(ty::PolyProjectionPredicate<'tcx>), - /// From the definition of `Trait` when you have something like <::B as Trait2>::C + /// From the definition of `Trait` when you have something like + /// `<::B as Trait2>::C`. TraitDef(ty::PolyProjectionPredicate<'tcx>), /// Bounds specified on an object type @@ -1367,7 +1368,7 @@ fn assemble_candidates_from_param_env<'cx, 'tcx>( ); } -/// In the case of a nested projection like <::FooT as Bar>::BarT, we may find +/// In the case of a nested projection like `<::FooT as Bar>::BarT`, we may find /// that the definition of `Foo` has some clues: /// /// ```ignore (illustrative) diff --git a/compiler/rustc_trait_selection/src/traits/select/mod.rs b/compiler/rustc_trait_selection/src/traits/select/mod.rs index 3f445f9ca464b..ddabea700d374 100644 --- a/compiler/rustc_trait_selection/src/traits/select/mod.rs +++ b/compiler/rustc_trait_selection/src/traits/select/mod.rs @@ -826,7 +826,7 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> { /// must be met of course). One obvious case this comes up is /// marker traits like `Send`. Think of a linked list: /// - /// struct List { data: T, next: Option>> } + /// struct List { data: T, next: Option>> } /// /// `Box>` will be `Send` if `T` is `Send` and /// `Option>>` is `Send`, and in turn From 14de94aec59bcd535f690e255a950ca76fcf2d5a Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 10 Oct 2022 18:29:17 +0200 Subject: [PATCH 6/7] Fix unclosed HTML tag in rustfmt doc --- src/tools/rustfmt/src/config/config_type.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tools/rustfmt/src/config/config_type.rs b/src/tools/rustfmt/src/config/config_type.rs index e37ed798cb559..c5e61658ad1ed 100644 --- a/src/tools/rustfmt/src/config/config_type.rs +++ b/src/tools/rustfmt/src/config/config_type.rs @@ -4,7 +4,7 @@ use crate::config::options::{IgnoreList, WidthHeuristics}; /// Trait for types that can be used in `Config`. pub(crate) trait ConfigType: Sized { /// Returns hint text for use in `Config::print_docs()`. For enum types, this is a - /// pipe-separated list of variants; for other types it returns "". + /// pipe-separated list of variants; for other types it returns ``. fn doc_hint() -> String; } From d565200270d425ab2d72b06109314c786676f593 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 10 Oct 2022 20:45:04 +0200 Subject: [PATCH 7/7] Fix unclosed HTML tag in clippy doc --- src/tools/clippy/clippy_utils/src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/tools/clippy/clippy_utils/src/lib.rs b/src/tools/clippy/clippy_utils/src/lib.rs index 42374fdd7bafd..e7e3625c078ab 100644 --- a/src/tools/clippy/clippy_utils/src/lib.rs +++ b/src/tools/clippy/clippy_utils/src/lib.rs @@ -2064,9 +2064,9 @@ pub fn fn_def_id(cx: &LateContext<'_>, expr: &Expr<'_>) -> Option { } } -/// Returns Option where String is a textual representation of the type encapsulated in the -/// slice iff the given expression is a slice of primitives (as defined in the -/// `is_recursively_primitive_type` function) and None otherwise. +/// Returns `Option` where String is a textual representation of the type encapsulated in +/// the slice iff the given expression is a slice of primitives (as defined in the +/// `is_recursively_primitive_type` function) and `None` otherwise. pub fn is_slice_of_primitives(cx: &LateContext<'_>, expr: &Expr<'_>) -> Option { let expr_type = cx.typeck_results().expr_ty_adjusted(expr); let expr_kind = expr_type.kind();