diff --git a/compiler/rustc_macros/src/diagnostics/mod.rs b/compiler/rustc_macros/src/diagnostics/mod.rs
index 09f05ce972f18..a036e61c37898 100644
--- a/compiler/rustc_macros/src/diagnostics/mod.rs
+++ b/compiler/rustc_macros/src/diagnostics/mod.rs
@@ -21,36 +21,25 @@ use synstructure::Structure;
 /// # extern crate rust_middle;
 /// # use rustc_middle::ty::Ty;
 /// #[derive(Diagnostic)]
-/// #[diag(borrowck_move_out_of_borrow, code = E0505)]
-/// pub struct MoveOutOfBorrowError<'tcx> {
+/// #[diag("this is an example message", code = E0123)]
+/// pub(crate) struct ExampleError<'tcx> {
 ///     pub name: Ident,
 ///     pub ty: Ty<'tcx>,
 ///     #[primary_span]
-///     #[label]
+///     #[label("with a label")]
 ///     pub span: Span,
-///     #[label(first_borrow_label)]
-///     pub first_borrow_span: Span,
-///     #[suggestion(code = "{name}.clone()")]
-///     pub clone_sugg: Option<(Span, Applicability)>
+///     #[label("with a label")]
+///     pub other_span: Span,
+///     #[suggestion("with a suggestion", code = "{name}.clone()")]
+///     pub opt_sugg: Option<(Span, Applicability)>,
 /// }
 /// ```
 ///
-/// ```fluent
-/// move_out_of_borrow = cannot move out of {$name} because it is borrowed
-///     .label = cannot move out of borrow
-///     .first_borrow_label = `{$ty}` first borrowed here
-///     .suggestion = consider cloning here
-/// ```
-///
 /// Then, later, to emit the error:
 ///
 /// ```ignore (rust)
-/// sess.emit_err(MoveOutOfBorrowError {
-///     expected,
-///     actual,
-///     span,
-///     first_borrow_span,
-///     clone_sugg: Some(suggestion, Applicability::MachineApplicable),
+/// sess.emit_err(ExampleError {
+///     name, ty, span, other_span, opt_sugg
 /// });
 /// ```
 ///
@@ -65,38 +54,24 @@ pub(super) fn diagnostic_derive(s: Structure<'_>) -> TokenStream {
 ///
 /// ```ignore (rust)
 /// #[derive(LintDiagnostic)]
-/// #[diag(lint_atomic_ordering_invalid_fail_success)]
-/// pub struct AtomicOrderingInvalidLint {
-///     method: Symbol,
-///     success_ordering: Symbol,
-///     fail_ordering: Symbol,
-///     #[label(fail_label)]
-///     fail_order_arg_span: Span,
-///     #[label(success_label)]
-///     #[suggestion(
-///         code = "std::sync::atomic::Ordering::{success_suggestion}",
-///         applicability = "maybe-incorrect"
+/// #[diag("unused attribute")]
+/// pub(crate) struct UnusedAttribute {
+///     #[suggestion("remove this attribute", code = "", applicability = "machine-applicable")]
+///     pub this: Span,
+///     #[note("attribute also specified here")]
+///     pub other: Span,
+///     #[warning(
+///         "this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!"
 ///     )]
-///     success_order_arg_span: Span,
+///     pub warning: bool,
 /// }
 /// ```
 ///
-/// ```fluent
-/// lint_atomic_ordering_invalid_fail_success = `{$method}`'s success ordering must be at least as strong as its failure ordering
-///     .fail_label = `{$fail_ordering}` failure ordering
-///     .success_label = `{$success_ordering}` success ordering
-///     .suggestion = consider using `{$success_suggestion}` success ordering instead
-/// ```
-///
 /// Then, later, to emit the error:
 ///
 /// ```ignore (rust)
-/// cx.emit_span_lint(INVALID_ATOMIC_ORDERING, fail_order_arg_span, AtomicOrderingInvalidLint {
-///     method,
-///     success_ordering,
-///     fail_ordering,
-///     fail_order_arg_span,
-///     success_order_arg_span,
+/// cx.emit_span_lint(UNUSED_ATTRIBUTES, span, UnusedAttribute {
+///     ...
 /// });
 /// ```
 ///
@@ -112,45 +87,25 @@ pub(super) fn lint_diagnostic_derive(s: Structure<'_>) -> TokenStream {
 ///
 /// ```ignore (rust)
 /// #[derive(Subdiagnostic)]
-/// pub enum ExpectedIdentifierLabel<'tcx> {
-///     #[label(expected_identifier)]
-///     WithoutFound {
-///         #[primary_span]
-///         span: Span,
-///     }
-///     #[label(expected_identifier_found)]
-///     WithFound {
-///         #[primary_span]
-///         span: Span,
-///         found: String,
-///     }
-/// }
-///
-/// #[derive(Subdiagnostic)]
-/// #[suggestion(style = "verbose",parser::raw_identifier)]
-/// pub struct RawIdentifierSuggestion<'tcx> {
-///     #[primary_span]
-///     span: Span,
-///     #[applicability]
-///     applicability: Applicability,
-///     ident: Ident,
+/// pub(crate) enum BuiltinUnusedDocCommentSub {
+///     #[help("use `//` for a plain comment")]
+///     PlainHelp,
+///     #[help("use `/* */` for a plain comment")]
+///     BlockHelp,
 /// }
 /// ```
-///
-/// ```fluent
-/// parser_expected_identifier = expected identifier
-///
-/// parser_expected_identifier_found = expected identifier, found {$found}
-///
-/// parser_raw_identifier = escape `{$ident}` to use it as an identifier
-/// ```
-///
-/// Then, later, to add the subdiagnostic:
+/// Then, later, use the subdiagnostic in a diagnostic:
 ///
 /// ```ignore (rust)
-/// diag.subdiagnostic(ExpectedIdentifierLabel::WithoutFound { span });
-///
-/// diag.subdiagnostic(RawIdentifierSuggestion { span, applicability, ident });
+/// #[derive(LintDiagnostic)]
+/// #[diag("unused doc comment")]
+/// pub(crate) struct BuiltinUnusedDocComment<'a> {
+///     pub kind: &'a str,
+///     #[label("rustdoc does not generate documentation for {$kind}")]
+///     pub label: Span,
+///     #[subdiagnostic]
+///     pub sub: BuiltinUnusedDocCommentSub,
+/// }
 /// ```
 pub(super) fn subdiagnostic_derive(s: Structure<'_>) -> TokenStream {
     SubdiagnosticDerive::new().into_tokens(s)