Struct Annotation 

pub struct Annotation { /* private fields */ }

A pointer to a subsequence in the end user’s input.

Also known as an annotation, the pointer can optionally contain a short message, typically describing in general terms what is being pointed to.

An annotation is either primary or secondary, depending on whether it was constructed via Annotation::primary or Annotation::secondary. Semantically, a primary annotation is meant to point to the “locus” of a diagnostic. Visually, the difference between a primary and a secondary annotation is usually just a different form of highlighting on the corresponding span.

Advice

The span on an annotation should be as specific as possible. For example, if there is a problem with a function call because one of its arguments has an invalid type, then the span should point to the specific argument and not to the entire function call.

Messages attached to annotations should also be as brief and specific as possible. Long messages could negative impact the quality of rendering.

Implementations

impl Annotation

pub fn primary(span: Span) -> Annotation

Create a “primary” annotation.

A primary annotation is meant to highlight the “locus” of a diagnostic. That is, it should point to something in the end user’s input that is the subject or “point” of a diagnostic.

A diagnostic may have many primary annotations. A diagnostic may not have any annotations, but if it does, at least one ought to be primary.

pub fn secondary(span: Span) -> Annotation

Create a “secondary” annotation.

A secondary annotation is meant to highlight relevant context for a diagnostic, but not to point to the “locus” of the diagnostic.

A diagnostic with only secondary annotations is usually not sensible, but it is allowed and will produce a reasonable rendering.

pub fn message<'a>(self, message: impl IntoDiagnosticMessage + 'a) -> Annotation

Attach a message to this annotation.

An annotation without a message will still have a presence in rendering. In particular, it will highlight the span association with this annotation in some way.

When a message is attached to an annotation, then it will be associated with the highlighted span in some way during rendering.

Types implementing IntoDiagnosticMessage

Callers can pass anything that implements std::fmt::Display directly. If callers want or need to avoid cloning the diagnostic message, then they can also pass a DiagnosticMessage directly.

pub fn set_message<'a>(&mut self, message: impl IntoDiagnosticMessage + 'a)

Sets the message on this annotation.

If one was already set, then this overwrites it.

This is useful if one needs to set the message on an annotation, and all one has is a &mut Annotation. For example, via Diagnostic::primary_annotation_mut.

pub fn get_message(&self) -> Option<&str>

Returns the message attached to this annotation, if one exists.

pub fn get_span(&self) -> &Span

Returns the Span associated with this annotation.

pub fn set_span(&mut self, span: Span)

Sets the span on this annotation.

pub fn push_tag(&mut self, tag: DiagnosticTag)

Attaches an additional tag to this annotation.

pub fn hide_snippet(&mut self, yes: bool)

Set whether or not the snippet on this annotation should be suppressed when rendering.

Such annotations are only rendered with their file name and range, if available. This is intended for backwards compatibility with Ruff diagnostics, which historically used TextRange::default to indicate a file-level diagnostic. In the new diagnostic model, a Span with a range of None should be used instead, as mentioned in the Span documentation.

TODO(brent) update this usage in Ruff and remove is_file_level entirely. See https://github.com/astral-sh/ruff/issues/19688, especially my first comment, for more details. As of 2025-09-26 we also use this to suppress snippet rendering for formatter diagnostics, which also need to have a range, so we probably can’t eliminate this entirely.

pub fn is_primary(&self) -> bool

Trait Implementations

impl Clone for Annotation

fn clone(&self) -> Annotation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Annotation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Annotation

impl GetSize for Annotation

fn get_heap_size(&self) -> usize

Determines how many bytes this object occupies inside the heap.

fn get_heap_size_with_tracker<TRACKER: GetSizeTracker>( &self, tracker: TRACKER, ) -> (usize, TRACKER)

Determines how many bytes this object occupies inside the heap while using a tracker.

fn get_stack_size() -> usize

Determines how may bytes this object occupies inside the stack.

fn get_size(&self) -> usize

Determines the total size of the object.

fn get_size_with_tracker<T>(&self, tracker: T) -> (usize, T)

where T: GetSizeTracker,

Determines the total size of the object while using a tracker.

impl Hash for Annotation

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Annotation

fn eq(&self, other: &Annotation) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Annotation