diff options
Diffstat (limited to 'compiler/rustc_errors/src')
| -rw-r--r-- | compiler/rustc_errors/src/diagnostic.rs | 25 | ||||
| -rw-r--r-- | compiler/rustc_errors/src/diagnostic_builder.rs | 40 |
2 files changed, 52 insertions, 13 deletions
diff --git a/compiler/rustc_errors/src/diagnostic.rs b/compiler/rustc_errors/src/diagnostic.rs index decbf03b9de..538e1a59ab8 100644 --- a/compiler/rustc_errors/src/diagnostic.rs +++ b/compiler/rustc_errors/src/diagnostic.rs @@ -30,7 +30,8 @@ pub enum DiagnosticId { Lint { name: String, has_future_breakage: bool }, } -/// For example a note attached to an error. +/// A "sub"-diagnostic attached to a parent diagnostic. +/// For example, a note attached to an error. #[derive(Clone, Debug, PartialEq, Hash, Encodable, Decodable)] pub struct SubDiagnostic { pub level: Level, @@ -124,6 +125,7 @@ impl Diagnostic { self.level = Level::Cancelled; } + /// Check if this diagnostic [was cancelled][Self::cancel()]. pub fn cancelled(&self) -> bool { self.level == Level::Cancelled } @@ -164,7 +166,7 @@ impl Diagnostic { self.note_expected_found_extra(expected_label, expected, found_label, found, &"", &"") } - pub fn note_unsuccessfull_coercion( + pub fn note_unsuccessful_coercion( &mut self, expected: DiagnosticStyledString, found: DiagnosticStyledString, @@ -241,6 +243,7 @@ impl Diagnostic { self } + /// Add a note attached to this diagnostic. pub fn note(&mut self, msg: &str) -> &mut Self { self.sub(Level::Note, msg, MultiSpan::new(), None); self @@ -252,33 +255,40 @@ impl Diagnostic { } /// Prints the span with a note above it. + /// This is like [`Diagnostic::note()`], but it gets its own span. pub fn span_note<S: Into<MultiSpan>>(&mut self, sp: S, msg: &str) -> &mut Self { self.sub(Level::Note, msg, sp.into(), None); self } + /// Add a warning attached to this diagnostic. pub fn warn(&mut self, msg: &str) -> &mut Self { self.sub(Level::Warning, msg, MultiSpan::new(), None); self } - /// Prints the span with a warn above it. + /// Prints the span with a warning above it. + /// This is like [`Diagnostic::warn()`], but it gets its own span. pub fn span_warn<S: Into<MultiSpan>>(&mut self, sp: S, msg: &str) -> &mut Self { self.sub(Level::Warning, msg, sp.into(), None); self } + /// Add a help message attached to this diagnostic. pub fn help(&mut self, msg: &str) -> &mut Self { self.sub(Level::Help, msg, MultiSpan::new(), None); self } /// Prints the span with some help above it. + /// This is like [`Diagnostic::help()`], but it gets its own span. pub fn span_help<S: Into<MultiSpan>>(&mut self, sp: S, msg: &str) -> &mut Self { self.sub(Level::Help, msg, sp.into(), None); self } + /// Show a suggestion that has multiple parts to it. + /// In other words, multiple changes need to be applied as part of this suggestion. pub fn multipart_suggestion( &mut self, msg: &str, @@ -299,6 +309,8 @@ impl Diagnostic { self } + /// Show multiple suggestions that have multiple parts. + /// See also [`Diagnostic::multipart_suggestion()`]. pub fn multipart_suggestions( &mut self, msg: &str, @@ -382,6 +394,7 @@ impl Diagnostic { self } + /// [`Diagnostic::span_suggestion()`] but you can set the [`SuggestionStyle`]. pub fn span_suggestion_with_style( &mut self, sp: Span, @@ -401,6 +414,7 @@ impl Diagnostic { self } + /// Always show the suggested change. pub fn span_suggestion_verbose( &mut self, sp: Span, @@ -419,6 +433,7 @@ impl Diagnostic { } /// Prints out a message with multiple suggested edits of the code. + /// See also [`Diagnostic::span_suggestion()`]. pub fn span_suggestions( &mut self, sp: Span, @@ -458,7 +473,7 @@ impl Diagnostic { self } - /// Prints out a message with for a suggestion without showing the suggested code. + /// Prints out a message for a suggestion without showing the suggested code. /// /// This is intended to be used for suggestions that are obvious in what the changes need to /// be from the message, showing the span label inline would be visually unpleasant @@ -481,7 +496,7 @@ impl Diagnostic { self } - /// Adds a suggestion to the json output, but otherwise remains silent/undisplayed in the cli. + /// Adds a suggestion to the JSON output that will not be shown in the CLI. /// /// This is intended to be used for suggestions that are *very* obvious in what the changes /// need to be from the message, but we still want other tools to be able to apply them. diff --git a/compiler/rustc_errors/src/diagnostic_builder.rs b/compiler/rustc_errors/src/diagnostic_builder.rs index c9259a1502c..f165a60336a 100644 --- a/compiler/rustc_errors/src/diagnostic_builder.rs +++ b/compiler/rustc_errors/src/diagnostic_builder.rs @@ -30,6 +30,15 @@ struct DiagnosticBuilderInner<'a> { allow_suggestions: bool, } +/// This is a helper macro for [`forward!`] that allows automatically adding documentation +/// that uses tokens from [`forward!`]'s input. +macro_rules! forward_inner_docs { + ($e:expr => $i:item) => { + #[doc = $e] + $i + } +} + /// In general, the `DiagnosticBuilder` uses deref to allow access to /// the fields and methods of the embedded `diagnostic` in a /// transparent way. *However,* many of the methods are intended to @@ -45,10 +54,11 @@ macro_rules! forward { pub fn $n:ident(&self, $($name:ident: $ty:ty),* $(,)?) -> &Self ) => { $(#[$attrs])* + forward_inner_docs!(concat!("See [`Diagnostic::", stringify!($n), "()`].") => pub fn $n(&self, $($name: $ty),*) -> &Self { self.diagnostic.$n($($name),*); self - } + }); }; // Forward pattern for &mut self -> &mut Self @@ -57,10 +67,11 @@ macro_rules! forward { pub fn $n:ident(&mut self, $($name:ident: $ty:ty),* $(,)?) -> &mut Self ) => { $(#[$attrs])* + forward_inner_docs!(concat!("See [`Diagnostic::", stringify!($n), "()`].") => pub fn $n(&mut self, $($name: $ty),*) -> &mut Self { self.0.diagnostic.$n($($name),*); self - } + }); }; // Forward pattern for &mut self -> &mut Self, with S: Into<MultiSpan> @@ -74,10 +85,11 @@ macro_rules! forward { ) -> &mut Self ) => { $(#[$attrs])* + forward_inner_docs!(concat!("See [`Diagnostic::", stringify!($n), "()`].") => pub fn $n<S: Into<MultiSpan>>(&mut self, $($name: $ty),*) -> &mut Self { self.0.diagnostic.$n($($name),*); self - } + }); }; } @@ -116,7 +128,7 @@ impl<'a> DiagnosticBuilder<'a> { /// Stashes diagnostic for possible later improvement in a different, /// later stage of the compiler. The diagnostic can be accessed with - /// the provided `span` and `key` through `.steal_diagnostic` on `Handler`. + /// the provided `span` and `key` through [`Handler::steal_diagnostic()`]. /// /// As with `buffer`, this is unless the handler has disabled such buffering. pub fn stash(self, span: Span, key: StashKey) { @@ -202,7 +214,7 @@ impl<'a> DiagnosticBuilder<'a> { } /// Labels all the given spans with the provided label. - /// See `span_label` for more information. + /// See [`Diagnostic::span_label()`] for more information. pub fn span_labels( &mut self, spans: impl IntoIterator<Item = Span>, @@ -233,7 +245,7 @@ impl<'a> DiagnosticBuilder<'a> { found_extra: &dyn fmt::Display, ) -> &mut Self); - forward!(pub fn note_unsuccessfull_coercion( + forward!(pub fn note_unsuccessful_coercion( &mut self, expected: DiagnosticStyledString, found: DiagnosticStyledString, @@ -254,6 +266,7 @@ impl<'a> DiagnosticBuilder<'a> { msg: &str, ) -> &mut Self); + /// See [`Diagnostic::multipart_suggestion()`]. pub fn multipart_suggestion( &mut self, msg: &str, @@ -267,6 +280,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::multipart_suggestions()`]. pub fn multipart_suggestions( &mut self, msg: &str, @@ -280,6 +294,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::tool_only_multipart_suggestion()`]. pub fn tool_only_multipart_suggestion( &mut self, msg: &str, @@ -293,6 +308,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::span_suggestion()`]. pub fn span_suggestion( &mut self, sp: Span, @@ -307,6 +323,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::span_suggestions()`]. pub fn span_suggestions( &mut self, sp: Span, @@ -321,6 +338,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::span_suggestion_short()`]. pub fn span_suggestion_short( &mut self, sp: Span, @@ -335,6 +353,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::span_suggestion_verbose()`]. pub fn span_suggestion_verbose( &mut self, sp: Span, @@ -349,6 +368,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::span_suggestion_hidden()`]. pub fn span_suggestion_hidden( &mut self, sp: Span, @@ -363,6 +383,7 @@ impl<'a> DiagnosticBuilder<'a> { self } + /// See [`Diagnostic::tool_only_span_suggestion()`] for more information. pub fn tool_only_span_suggestion( &mut self, sp: Span, @@ -380,19 +401,22 @@ impl<'a> DiagnosticBuilder<'a> { forward!(pub fn set_span<S: Into<MultiSpan>>(&mut self, sp: S) -> &mut Self); forward!(pub fn code(&mut self, s: DiagnosticId) -> &mut Self); + /// Allow attaching suggestions this diagnostic. + /// If this is set to `false`, then any suggestions attached with the `span_suggestion_*` + /// methods after this is set to `false` will be ignored. pub fn allow_suggestions(&mut self, allow: bool) -> &mut Self { self.0.allow_suggestions = allow; self } /// Convenience function for internal use, clients should use one of the - /// struct_* methods on Handler. + /// `struct_*` methods on [`Handler`]. crate fn new(handler: &'a Handler, level: Level, message: &str) -> DiagnosticBuilder<'a> { DiagnosticBuilder::new_with_code(handler, level, None, message) } /// Convenience function for internal use, clients should use one of the - /// struct_* methods on Handler. + /// `struct_*` methods on [`Handler`]. crate fn new_with_code( handler: &'a Handler, level: Level, |