fix!: Rename title to primary_title

Muscraft · Muscraft · commit 00d0d3947c3d · 2025-08-27T09:19:13.000-06:00
diff --git a/benches/bench.rs b/benches/bench.rs
@@ -25,7 +25,7 @@ fn simple() -> String {
         }
     }"#;
     let message = &[
-        Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(
+        Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308")).element(
             Snippet::source(source)
                 .line_start(51)
                 .path("src/format.rs")
@@ -69,15 +69,17 @@ fn fold(bencher: divan::Bencher<'_, '_>, context: usize) {
             (input, span)
         })
         .bench_values(|(input, span)| {
-            let message = &[
-                Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(
-                    Snippet::source(&input).path("src/format.rs").annotation(
-                        AnnotationKind::Context
-                            .span(span)
-                            .label("expected `Option<String>` because of return type"),
-                    ),
-                ),
-            ];
+            let message =
+                &[
+                    Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
+                        .element(
+                            Snippet::source(&input).path("src/format.rs").annotation(
+                                AnnotationKind::Context
+                                    .span(span)
+                                    .label("expected `Option<String>` because of return type"),
+                            ),
+                        ),
+                ];
 
             let renderer = Renderer::plain();
             let rendered = renderer.render(message);
diff --git a/examples/custom_error.rs b/examples/custom_error.rs
@@ -18,7 +18,7 @@ pub static C: u32 = 0 - 1;
     let message = &[Group::with_title(
         Level::ERROR
             .with_name(Some("error: internal compiler error"))
-            .title("could not evaluate static initializer")
+            .primary_title("could not evaluate static initializer")
             .id("E0080"),
     )
     .element(
diff --git a/examples/custom_level.rs b/examples/custom_level.rs
@@ -32,7 +32,7 @@ fn main() {
     let message = &[
         Group::with_title(
             Level::ERROR
-                .title("`break` with value from a `while` loop")
+                .primary_title("`break` with value from a `while` loop")
                 .id("E0571"),
         )
         .element(
@@ -53,7 +53,7 @@ fn main() {
         Group::with_title(
             Level::HELP
                 .with_name(Some("suggestion"))
-                .title("use `break` on its own without a value inside this `while` loop"),
+                .primary_title("use `break` on its own without a value inside this `while` loop"),
         )
         .element(
             Snippet::source(source)
diff --git a/examples/expected_type.rs b/examples/expected_type.rs
@@ -7,7 +7,7 @@ fn main() {
                 range: <22, 25>,"#;
     let message =
         &[
-            Group::with_title(Level::ERROR.title("expected type, found `22`")).element(
+            Group::with_title(Level::ERROR.primary_title("expected type, found `22`")).element(
                 Snippet::source(source)
                     .line_start(26)
                     .path("examples/footer.rs")
diff --git a/examples/footer.rs b/examples/footer.rs
@@ -3,15 +3,15 @@ use annotate_snippets::{AnnotationKind, Group, Level, Renderer, Snippet};
 fn main() {
     let message =
         &[
-            Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(
+            Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308")).element(
                 Snippet::source("        slices: vec![\"A\",")
                     .line_start(13)
                     .path("src/multislice.rs")
                     .annotation(AnnotationKind::Primary.span(21..24).label(
                         "expected struct `annotate_snippets::snippet::Slice`, found reference",
                     )),
             ),
-            Group::with_title(Level::NOTE.title(
+            Group::with_title(Level::NOTE.primary_title(
                 "expected type: `snippet::Annotation`\n   found type: `__&__snippet::Annotation`",
             )),
         ];
diff --git a/examples/format.rs b/examples/format.rs
@@ -24,7 +24,7 @@ fn main() {
         }
     }"#;
     let message = &[
-        Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(
+        Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308")).element(
             Snippet::source(source)
                 .line_start(51)
                 .path("src/format.rs")
diff --git a/examples/highlight_message.rs b/examples/highlight_message.rs
@@ -34,7 +34,7 @@ fn main() {
     );
 
     let message = &[
-        Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+        Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
             .element(
                 Snippet::source(source)
                     .path("$DIR/highlighting.rs")
@@ -50,7 +50,7 @@ fn main() {
                     ),
             )
             .element(Level::NOTE.message(&message)),
-        Group::with_title(Level::NOTE.title("function defined here")).element(
+        Group::with_title(Level::NOTE.primary_title("function defined here")).element(
             Snippet::source(source)
                 .path("$DIR/highlighting.rs")
                 .annotation(AnnotationKind::Context.span(200..333).label(""))
diff --git a/examples/highlight_source.rs b/examples/highlight_source.rs
@@ -9,7 +9,7 @@ const CON: Vec<i32> = vec![1, 2, 3]; //~ ERROR E0010
 //~| ERROR cannot call non-const method
 fn main() {}
 "#;
-    let message = &[Group::with_title(Level::ERROR.title("allocations are not allowed in constants")
+    let message = &[Group::with_title(Level::ERROR.primary_title("allocations are not allowed in constants")
         .id("E0010"))
         .element(
             Snippet::source(source)
diff --git a/examples/id_hyperlink.rs b/examples/id_hyperlink.rs
@@ -9,7 +9,7 @@ fn main() {
 "#;
     let message = &[Group::with_title(
         Level::ERROR
-            .title("mismatched types")
+            .primary_title("mismatched types")
             .id("E0308")
             .id_url("https://doc.rust-lang.org/error_codes/E0308.html"),
     )
diff --git a/examples/multislice.rs b/examples/multislice.rs
@@ -1,19 +1,21 @@
 use annotate_snippets::{Annotation, Group, Level, Renderer, Snippet};
 
 fn main() {
-    let message = &[Group::with_title(Level::ERROR.title("mismatched types"))
-        .element(
-            Snippet::<Annotation<'_>>::source("Foo")
-                .line_start(51)
-                .fold(false)
-                .path("src/format.rs"),
-        )
-        .element(
-            Snippet::<Annotation<'_>>::source("Faa")
-                .line_start(129)
-                .fold(false)
-                .path("src/display.rs"),
-        )];
+    let message = &[
+        Group::with_title(Level::ERROR.primary_title("mismatched types"))
+            .element(
+                Snippet::<Annotation<'_>>::source("Foo")
+                    .line_start(51)
+                    .fold(false)
+                    .path("src/format.rs"),
+            )
+            .element(
+                Snippet::<Annotation<'_>>::source("Faa")
+                    .line_start(129)
+                    .fold(false)
+                    .path("src/display.rs"),
+            ),
+    ];
 
     let renderer = Renderer::styled();
     anstream::println!("{}", renderer.render(message));
diff --git a/examples/struct_name_as_context.rs b/examples/struct_name_as_context.rs
@@ -9,23 +9,18 @@ fn main() {
     field6: usize,
 }
 "#;
-    let message =
-        &[
-            Group::with_title(
-                Level::ERROR.title("functions are not allowed in struct definitions"),
-            )
-            .element(
-                Snippet::source(source)
-                    .path("$DIR/struct_name_as_context.rs")
-                    .annotation(AnnotationKind::Primary.span(91..102))
-                    .annotation(AnnotationKind::Visible.span(0..8)),
-            )
-            .element(
-                Level::HELP.message(
-                    "unlike in C++, Java, and C#, functions are declared in `impl` blocks",
-                ),
-            ),
-        ];
+    let message = &[Group::with_title(
+        Level::ERROR.primary_title("functions are not allowed in struct definitions"),
+    )
+    .element(
+        Snippet::source(source)
+            .path("$DIR/struct_name_as_context.rs")
+            .annotation(AnnotationKind::Primary.span(91..102))
+            .annotation(AnnotationKind::Visible.span(0..8)),
+    )
+    .element(
+        Level::HELP.message("unlike in C++, Java, and C#, functions are declared in `impl` blocks"),
+    )];
 
     let renderer = Renderer::styled();
     anstream::println!("{}", renderer.render(message));
diff --git a/src/level.rs b/src/level.rs
@@ -53,7 +53,9 @@ impl<'a> Level<'a> {
 }
 
 impl<'a> Level<'a> {
-    /// A text [`Element`][crate::Element] to start a [`Group`][crate::Group]
+    /// Creates a [`Title`] that has bolded text, and is
+    /// intended to be used with the "primary" (first)
+    /// [`Group`][crate::Group] in a [`Report`][crate::Report].
     ///
     /// See [`Group::with_title`][crate::Group::with_title]
     ///
@@ -70,10 +72,10 @@ impl<'a> Level<'a> {
     /// ```rust
     /// # use annotate_snippets::{Group, Snippet, AnnotationKind, Level};
     /// let input = &[
-    ///     Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+    ///     Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
     /// ];
     /// ```
-    pub fn title(self, text: impl Into<Cow<'a, str>>) -> Title<'a> {
+    pub fn primary_title(self, text: impl Into<Cow<'a, str>>) -> Title<'a> {
         Title {
             level: self,
             id: None,
@@ -97,7 +99,7 @@ impl<'a> Level<'a> {
     /// ```rust
     /// # use annotate_snippets::{Group, Snippet, AnnotationKind, Level};
     /// let input = &[
-    ///     Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+    ///     Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
     ///         .element(
     ///             Level::NOTE
     ///                 .no_name()
@@ -166,7 +168,7 @@ impl<'a> Level<'a> {
     ///     let s: &str = include_bytes!("file.txt");   //~ ERROR mismatched types
     /// }"#;
     /// let input = &[
-    ///     Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+    ///     Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
     ///         .element(
     ///             Snippet::source(source)
     ///                 .path("$DIR/mismatched-types.rs")
diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs
@@ -22,7 +22,7 @@
 //!
 //!  Group::with_title(
 //!      Level::ERROR
-//!          .title("unresolved import `baz::zed`")
+//!          .primary_title("unresolved import `baz::zed`")
 //!          .id("E0432")
 //!  )
 //!  .element(
diff --git a/src/snippet.rs b/src/snippet.rs
@@ -132,7 +132,7 @@ pub struct Padding;
 
 /// A text [`Element`] to start a [`Group`]
 ///
-/// See [`Level::title`] to create this.
+/// See [`Level::primary_title`] to create this.
 #[derive(Clone, Debug)]
 pub struct Title<'a> {
     pub(crate) level: Level<'a>,
@@ -433,7 +433,7 @@ impl<'a> Patch<'a> {
 /// ```rust
 /// # use annotate_snippets::{Group, Snippet, AnnotationKind, Level, Origin};
 /// let input = &[
-///     Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+///     Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
 ///         .element(
 ///             Origin::path("$DIR/mismatched-types.rs")
 ///         )
diff --git a/tests/color/ann_eof.rs b/tests/color/ann_eof.rs
@@ -5,7 +5,7 @@ use snapbox::{assert_data_eq, file};
 #[test]
 fn case() {
     let input = &[
-        Group::with_title(Level::ERROR.title("expected `.`, `=`")).element(
+        Group::with_title(Level::ERROR.primary_title("expected `.`, `=`")).element(
             Snippet::source("asdf")
                 .path("Cargo.toml")
                 .line_start(1)
diff --git a/tests/color/ann_insertion.rs b/tests/color/ann_insertion.rs
@@ -5,7 +5,7 @@ use snapbox::{assert_data_eq, file};
 #[test]
 fn case() {
     let input = &[
-        Group::with_title(Level::ERROR.title("expected `.`, `=`")).element(
+        Group::with_title(Level::ERROR.primary_title("expected `.`, `=`")).element(
             Snippet::source("asf")
                 .path("Cargo.toml")
                 .line_start(1)
diff --git a/tests/color/ann_multiline.rs b/tests/color/ann_multiline.rs
@@ -11,7 +11,7 @@ fn case() {
 
     let input = &[Group::with_title(
         Level::ERROR
-            .title("pattern does not mention fields `lineno`, `content`")
+            .primary_title("pattern does not mention fields `lineno`, `content`")
             .id("E0027"),
     )
     .element(
diff --git a/tests/color/ann_multiline2.rs b/tests/color/ann_multiline2.rs
@@ -9,19 +9,22 @@ of an edge case of an annotation overflowing
 to exactly one character on next line.
 "#;
 
-    let input = &[
-        Group::with_title(Level::ERROR.title("spacing error found").id("E####")).element(
-            Snippet::source(source)
-                .path("foo.txt")
-                .line_start(26)
-                .fold(false)
-                .annotation(
-                    AnnotationKind::Primary
-                        .span(11..19)
-                        .label("this should not be on separate lines"),
-                ),
-        ),
-    ];
+    let input = &[Group::with_title(
+        Level::ERROR
+            .primary_title("spacing error found")
+            .id("E####"),
+    )
+    .element(
+        Snippet::source(source)
+            .path("foo.txt")
+            .line_start(26)
+            .fold(false)
+            .annotation(
+                AnnotationKind::Primary
+                    .span(11..19)
+                    .label("this should not be on separate lines"),
+            ),
+    )];
     let expected = file!["ann_multiline2.term.svg"];
     let renderer = Renderer::styled();
     assert_data_eq!(renderer.render(input), expected);
diff --git a/tests/color/ann_removed_nl.rs b/tests/color/ann_removed_nl.rs
@@ -5,7 +5,7 @@ use snapbox::{assert_data_eq, file};
 #[test]
 fn case() {
     let input = &[
-        Group::with_title(Level::ERROR.title("expected `.`, `=`")).element(
+        Group::with_title(Level::ERROR.primary_title("expected `.`, `=`")).element(
             Snippet::source("asdf")
                 .path("Cargo.toml")
                 .line_start(1)
diff --git a/tests/color/ensure_emoji_highlight_width.rs b/tests/color/ensure_emoji_highlight_width.rs
@@ -7,7 +7,7 @@ fn case() {
     let source = r#""haha this isn't a valid name 🐛" = { package = "libc", version = "0.1" }
 "#;
 
-    let input = &[Group::with_title(Level::ERROR.title("invalid character ` ` in package name: `haha this isn't a valid name 🐛`, characters must be Unicode XID characters (numbers, `-`, `_`, or most letters)"))
+    let input = &[Group::with_title(Level::ERROR.primary_title("invalid character ` ` in package name: `haha this isn't a valid name 🐛`, characters must be Unicode XID characters (numbers, `-`, `_`, or most letters)"))
         .element(
             Snippet::source(source)
                 .path("<file>")
diff --git a/tests/color/first_snippet_is_primary.rs b/tests/color/first_snippet_is_primary.rs
@@ -12,7 +12,7 @@ fn case() {
 }"#;
 
     let input = &[
-        Group::with_title(Level::ERROR.title("mismatched types").id("E0308"))
+        Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308"))
             .element(
                 Snippet::source(file_txt_source)
                     .line_start(3)
diff --git a/tests/color/fold_ann_multiline.rs b/tests/color/fold_ann_multiline.rs
@@ -29,7 +29,7 @@ fn case() {
 "#;
 
     let input = &[
-        Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(
+        Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308")).element(
             Snippet::source(source)
                 .path("src/format.rs")
                 .line_start(51)
diff --git a/tests/color/fold_bad_origin_line.rs b/tests/color/fold_bad_origin_line.rs
@@ -9,7 +9,7 @@ fn case() {
 invalid syntax
 "#;
 
-    let input = &[Group::with_title(Level::ERROR.title("")).element(
+    let input = &[Group::with_title(Level::ERROR.primary_title("")).element(
         Snippet::source(source)
             .path("path/to/error.rs")
             .line_start(1)
diff --git a/tests/color/fold_leading.rs b/tests/color/fold_leading.rs
@@ -19,7 +19,7 @@ workspace = 20
 
     let input = &[Group::with_title(
         Level::ERROR
-            .title("invalid type: integer `20`, expected a bool")
+            .primary_title("invalid type: integer `20`, expected a bool")
             .id("E0308"),
     )
     .element(
diff --git a/tests/color/fold_trailing.rs b/tests/color/fold_trailing.rs
diff --git a/tests/color/issue_9.rs b/tests/color/issue_9.rs
diff --git a/tests/color/multiline_removal_suggestion.rs b/tests/color/multiline_removal_suggestion.rs
diff --git a/tests/color/multiple_annotations.rs b/tests/color/multiple_annotations.rs
diff --git a/tests/color/simple.rs b/tests/color/simple.rs
diff --git a/tests/color/strip_line.rs b/tests/color/strip_line.rs
diff --git a/tests/color/strip_line_char.rs b/tests/color/strip_line_char.rs
diff --git a/tests/color/strip_line_non_ws.rs b/tests/color/strip_line_non_ws.rs
diff --git a/tests/formatter.rs b/tests/formatter.rs
diff --git a/tests/rustc_tests.rs b/tests/rustc_tests.rs

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ pub static C: u32 = 0 - 1;`
`18`	`18`	`let message = &[Group::with_title(`
`19`	`19`	`Level::ERROR`
`20`	`20`	`.with_name(Some("error: internal compiler error"))`
`21`		`- .title("could not evaluate static initializer")`
	`21`	`+ .primary_title("could not evaluate static initializer")`
`22`	`22`	`.id("E0080"),`
`23`	`23`	`)`
`24`	`24`	`.element(`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ fn main() {`
`24`	`24`	`}`
`25`	`25`	`}"#;`
`26`	`26`	`let message = &[`
`27`		`- Group::with_title(Level::ERROR.title("mismatched types").id("E0308")).element(`
	`27`	`+ Group::with_title(Level::ERROR.primary_title("mismatched types").id("E0308")).element(`
`28`	`28`	`Snippet::source(source)`
`29`	`29`	`.line_start(51)`
`30`	`30`	`.path("src/format.rs")`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ fn main() {`
`9`	`9`	`"#;`
`10`	`10`	`let message = &[Group::with_title(`
`11`	`11`	`Level::ERROR`
`12`		`- .title("mismatched types")`
	`12`	`+ .primary_title("mismatched types")`
`13`	`13`	`.id("E0308")`
`14`	`14`	`.id_url("https://doc.rust-lang.org/error_codes/E0308.html"),`
`15`	`15`	`)`