Enum Annotation 

pub enum Annotation {
    Kind(Arc<str>),
    DocSnippet(Arc<str>),
    Keybinding(Vec<KeyChord>),
    Source(Arc<str>),
    Custom {
        text: Arc<str>,
        slot: Arc<str>,
    },
    Styled {
        category: Arc<str>,
        segments: Vec<AnnotationSegment>,
    },
}

One annotation attached to a completion candidate.

MARG.1 (2026-06-03): replaces the previous untyped annotations: Vec<String> with a tagged enum so the renderer can color-code each annotation by category. The payload preserves semantic info (e.g. Keybinding keeps the chord list for future affordances like “show conflicts” or “click to edit binding”); display-time formatting is the renderer’s job via Annotation::display_text.

Variants are open-by-versioning: adding a variant is a minor-version bump; removing one is breaking. The Custom variant is the escape hatch for in-tree extension crates (and future WASM plugins) that don’t fit any built-in variant — payload includes a slot string the renderer resolves against the theme.

Severity variant is intentionally omitted in MARG.1 — no consumer yet (diagnostic-suggestion candidates land in a later slice). Adding it when needed is non-breaking.

See docs/dev/architecture/marginalia.md for the data-model rationale and the rejected String + style and pre-styled- spans alternatives.

Variants

Kind(Arc<str>)

Category icon like → (motion), : (ex-command), f (file). Emitted by KindLabelAnnotator. Renderer styles with the kind-annotation slot.

DocSnippet(Arc<str>)

First line of a command’s doc string. Emitted by DocSnippetAnnotator. Renderer styles with the doc annotation slot.

Keybinding(Vec<KeyChord>)

Chord(s) bound to this candidate’s command. Emitted by the keybinding annotator (MARG.2). The renderer formats chords via [KeyChord]’s Display impl and styles with the keybinding annotation slot. Empty vec is invalid — annotators should not emit this variant when no chord binds. Most candidates have 0-1 chords; the rare multi-binding case uses Vec rather than SmallVec to avoid an extra crate dep pre-v1 — perf-driven storage swap deferred until a bench shows it matters.

Source(Arc<str>)

Provenance: which crate / mode / user-config defined this command. Arc<str> because most candidates share the same source label ("builtin", "lsp", "user-init"); copy-by-reference is cheaper than cloning the string per-candidate.

Custom

Escape hatch for plugin-contributed annotations that don’t fit any built-in variant. The annotator pre-formats text; slot names a theme slot the renderer resolves (unknown slot falls back to the plugin-annotation default).

Fields

text: Arc<str>

slot: Arc<str>

Styled

MARG §8: a single column cell whose text is colored per segment. Generalizes Custom to N slots — used for the file-permission string (drwxr-xr-x, one segment per bit class) and any future multi-colored field (size+unit, path head/tail, git status). Each segment carries a slot KEY, never a resolved color, so theme resolution stays at the render seam. category keys the column exactly like the single-variant categories.

Fields

category: Arc<str>

segments: Vec<AnnotationSegment>

Implementations

impl Annotation

pub fn display_text(&self) -> Cow<'_, str>

Borrow-or-format the annotation’s text for paint. String- payload variants return a borrowed Cow; structured variants (Keybinding) format on demand.

pub fn category(&self) -> &str

Stable category key the renderer pattern-matches on to pick a theme slot. Variant names mirror the theme slot suffix (annotation_kind, annotation_doc, …). Custom returns its slot field; unknown slots fall back to annotation_plugin at paint time.

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 PartialEq for Annotation

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Annotation