Auto merge of #101558 - JhonnyBillM:session-diagnostic-to-diagnostic-handler-refactor, r=davidtwco

Move and rename `SessionDiagnostic` & `SessionSubdiagnostic` traits and macros

After PR #101434, we want to:
- [x] Move `SessionDiagnostic` to `rustc_errors`.
- [x] Add `emit_` methods that accept `impl SessionDiagnostic` to `Handler`.
- [x] _(optional)_ Rename trait `SessionDiagnostic` to `DiagnosticHandler`.
- [x] _(optional)_ Rename macro `SessionDiagnostic` to `DiagnosticHandler`.
- [x] Update Rustc Dev Guide and Docs to reflect these changes. https://github.com/rust-lang/rustc-dev-guide/pull/1460

Now I am having build issues getting the compiler to build when trying to rename the macro.

<details>
  <summary>See diagnostics errors and context when building.</summary>

```
error: diagnostics should only be created in `SessionDiagnostic`/`AddSubdiagnostic` impls
  --> compiler/rustc_attr/src/session_diagnostics.rs:13:10
   |
13 |   #[derive(DiagnosticHandler)]
   |            ^^^^^^^^^^^^^^^^^ in this derive macro expansion
   |
  ::: /Users/jhonny/.cargo/registry/src/github.com-1ecc6299db9ec823/synstructure-0.12.6/src/macros.rs:94:9
   |
94 | /         pub fn $derives(
95 | |             i: $crate::macros::TokenStream
96 | |         ) -> $crate::macros::TokenStream {
   | |________________________________________- in this expansion of `#[derive(DiagnosticHandler)]`
   |
note: the lint level is defined here
  --> compiler/rustc_attr/src/lib.rs:10:9
   |
10 | #![deny(rustc::diagnostic_outside_of_impl)]
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

```

And also this one:

```
error: diagnostics should only be created in `SessionDiagnostic`/`AddSubdiagnostic` impls
   --> compiler/rustc_attr/src/session_diagnostics.rs:213:32
    |
213 |         let mut diag = handler.struct_span_err_with_code(
    |                                ^^^^^^^^^^^^^^^^^^^^^^^^^
```

> **Note**
> Can't find where this message is coming from, because you can see in [this experimental branch](https://github.com/JhonnyBillM/rust/tree/experimental/trying-to-rename-session-diagnostic-macro)  that I updated all errors and diags to say:
> error: diagnostics should only be created in **`DiagnosticHandler`**/`AddSubdiagnostic` impls
> and not:
> error: diagnostics should only be created in **`SessionDiagnostic`**/`AddSubdiagnostic` impls

</details>

I tried building the compiler in different ways (playing with the stages etc), but nothing worked.

## Question

**Do we need to build or do something different when renaming a macro and identifiers?**

For context, see experimental commit https://github.com/JhonnyBillM/rust/commit/f2193a98b44db3f2af77a878824b152cdf0d34a5 where the macro and symbols are renamed, but it doesn't compile.

3 files changed, 56 insertions, 11 deletions

diff --git a/compiler/rustc_errors/src/diagnostic.rs b/compiler/rustc_errors/src/diagnostic.rs
index 6dfb6b11b16..a52e95e92d5 100644
--- a/compiler/rustc_errors/src/diagnostic.rs
+++ b/compiler/rustc_errors/src/diagnostic.rs
@@ -35,7 +35,7 @@ pub enum DiagnosticArgValue<'source> {
     Number(usize),
 }
 
-/// Converts a value of a type into a `DiagnosticArg` (typically a field of a `SessionDiagnostic`
+/// Converts a value of a type into a `DiagnosticArg` (typically a field of an `IntoDiagnostic`
 /// struct). Implemented as a custom trait rather than `From` so that it is implemented on the type
 /// being converted rather than on `DiagnosticArgValue`, which enables types from other `rustc_*`
 /// crates to implement this.
@@ -176,9 +176,10 @@ impl IntoDiagnosticArg for hir::ConstContext {
 }
 
 /// Trait implemented by error types. This should not be implemented manually. Instead, use
-/// `#[derive(SessionSubdiagnostic)]` -- see [rustc_macros::SessionSubdiagnostic].
-#[rustc_diagnostic_item = "AddSubdiagnostic"]
-pub trait AddSubdiagnostic {
+/// `#[derive(Subdiagnostic)]` -- see [rustc_macros::Subdiagnostic].
+#[cfg_attr(bootstrap, rustc_diagnostic_item = "AddSubdiagnostic")]
+#[cfg_attr(not(bootstrap), rustc_diagnostic_item = "AddToDiagnostic")]
+pub trait AddToDiagnostic {
     /// Add a subdiagnostic to an existing diagnostic.
     fn add_to_diagnostic(self, diag: &mut Diagnostic);
 }
@@ -891,9 +892,9 @@ impl Diagnostic {
         self
     }
 
-    /// Add a subdiagnostic from a type that implements `SessionSubdiagnostic` - see
-    /// [rustc_macros::SessionSubdiagnostic].
-    pub fn subdiagnostic(&mut self, subdiagnostic: impl AddSubdiagnostic) -> &mut Self {
+    /// Add a subdiagnostic from a type that implements `Subdiagnostic` - see
+    /// [rustc_macros::Subdiagnostic].
+    pub fn subdiagnostic(&mut self, subdiagnostic: impl AddToDiagnostic) -> &mut Self {
         subdiagnostic.add_to_diagnostic(self);
         self
     }
diff --git a/compiler/rustc_errors/src/diagnostic_builder.rs b/compiler/rustc_errors/src/diagnostic_builder.rs
index 7e29dc207ac..b4ba65ca96d 100644
--- a/compiler/rustc_errors/src/diagnostic_builder.rs
+++ b/compiler/rustc_errors/src/diagnostic_builder.rs
@@ -13,6 +13,16 @@ use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
 use std::thread::panicking;
 
+/// Trait implemented by error types. This should not be implemented manually. Instead, use
+/// `#[derive(Diagnostic)]` -- see [rustc_macros::Diagnostic].
+#[cfg_attr(bootstrap, rustc_diagnostic_item = "SessionDiagnostic")]
+#[cfg_attr(not(bootstrap), rustc_diagnostic_item = "IntoDiagnostic")]
+pub trait IntoDiagnostic<'a, T: EmissionGuarantee = ErrorGuaranteed> {
+    /// Write out as a diagnostic out of `Handler`.
+    #[must_use]
+    fn into_diagnostic(self, handler: &'a Handler) -> DiagnosticBuilder<'a, T>;
+}
+
 /// Used for emitting structured error messages and other diagnostic information.
 ///
 /// If there is some state in a downstream crate you would like to
@@ -570,7 +580,7 @@ impl<'a, G: EmissionGuarantee> DiagnosticBuilder<'a, G> {
 
     forward!(pub fn subdiagnostic(
         &mut self,
-        subdiagnostic: impl crate::AddSubdiagnostic
+        subdiagnostic: impl crate::AddToDiagnostic
     ) -> &mut Self);
 }
 
diff --git a/compiler/rustc_errors/src/lib.rs b/compiler/rustc_errors/src/lib.rs
index 6f969bfcc53..68971cebc35 100644
--- a/compiler/rustc_errors/src/lib.rs
+++ b/compiler/rustc_errors/src/lib.rs
@@ -60,6 +60,7 @@ mod snippet;
 mod styled_buffer;
 pub mod translation;
 
+pub use diagnostic_builder::IntoDiagnostic;
 pub use snippet::Style;
 
 pub type PResult<'a, T> = Result<T, DiagnosticBuilder<'a, ErrorGuaranteed>>;
@@ -370,7 +371,7 @@ impl fmt::Display for ExplicitBug {
 impl error::Error for ExplicitBug {}
 
 pub use diagnostic::{
-    AddSubdiagnostic, DecorateLint, Diagnostic, DiagnosticArg, DiagnosticArgFromDisplay,
+    AddToDiagnostic, DecorateLint, Diagnostic, DiagnosticArg, DiagnosticArgFromDisplay,
     DiagnosticArgValue, DiagnosticId, DiagnosticStyledString, IntoDiagnosticArg, SubDiagnostic,
 };
 pub use diagnostic_builder::{DiagnosticBuilder, EmissionGuarantee, LintDiagnosticBuilder};
@@ -436,11 +437,11 @@ struct HandlerInner {
     /// have been converted.
     check_unstable_expect_diagnostics: bool,
 
-    /// Expected [`Diagnostic`]s store a [`LintExpectationId`] as part of
+    /// Expected [`Diagnostic`][diagnostic::Diagnostic]s store a [`LintExpectationId`] as part of
     /// the lint level. [`LintExpectationId`]s created early during the compilation
     /// (before `HirId`s have been defined) are not stable and can therefore not be
     /// stored on disk. This buffer stores these diagnostics until the ID has been
-    /// replaced by a stable [`LintExpectationId`]. The [`Diagnostic`]s are the
+    /// replaced by a stable [`LintExpectationId`]. The [`Diagnostic`][diagnostic::Diagnostic]s are the
     /// submitted for storage and added to the list of fulfilled expectations.
     unstable_expect_diagnostics: Vec<Diagnostic>,
 
@@ -1028,6 +1029,39 @@ impl Handler {
         self.inner.borrow_mut().emit_diagnostic(diagnostic)
     }
 
+    pub fn emit_err<'a>(&'a self, err: impl IntoDiagnostic<'a>) -> ErrorGuaranteed {
+        self.create_err(err).emit()
+    }
+
+    pub fn create_err<'a>(
+        &'a self,
+        err: impl IntoDiagnostic<'a>,
+    ) -> DiagnosticBuilder<'a, ErrorGuaranteed> {
+        err.into_diagnostic(self)
+    }
+
+    pub fn create_warning<'a>(
+        &'a self,
+        warning: impl IntoDiagnostic<'a, ()>,
+    ) -> DiagnosticBuilder<'a, ()> {
+        warning.into_diagnostic(self)
+    }
+
+    pub fn emit_warning<'a>(&'a self, warning: impl IntoDiagnostic<'a, ()>) {
+        self.create_warning(warning).emit()
+    }
+
+    pub fn create_fatal<'a>(
+        &'a self,
+        fatal: impl IntoDiagnostic<'a, !>,
+    ) -> DiagnosticBuilder<'a, !> {
+        fatal.into_diagnostic(self)
+    }
+
+    pub fn emit_fatal<'a>(&'a self, fatal: impl IntoDiagnostic<'a, !>) -> ! {
+        self.create_fatal(fatal).emit()
+    }
+
     fn emit_diag_at_span(
         &self,
         mut diag: Diagnostic,