Struct Commented 

pub struct Commented<T>(pub T, pub String);

Attach an inline YAML comment to a value when serializing.

Requires the comments feature, which is enabled by default.

This wrapper lets you annotate a scalar with an inline YAML comment that is emitted after the value when using block style. The typical form is: value # comment. This is the most useful when deserializing the anchor reference (so a human reader can see what a referenced value represents).

Comment is also captured into its field when deserializing YAML.

Behavior

• Block style (default): the comment appears after the scalar on the same line.
• Flow style (inside [ ... ] or { ... }): comments are suppressed to keep the flow representation compact and unambiguous.
• Complex values (sequences/maps/structs): the comment is ignored; only the inner value is serialized to preserve indentation and layout.
• Newlines in comments are sanitized to spaces so the comment remains on a single line (e.g., “a\nb” becomes “a b”).
• Deserialization of Commented<T> captures nearby source comments when the serde-saphyr deserializer can provide them. Other deserializers treat it transparently and produce an empty comment string.
• Comment capture is use-site oriented for replayed YAML. Comments from an anchor definition are not copied through aliases or merge keys; a field materialized by <<: *defaults does not inherit comments that were written above the field inside &defaults.
• For container values, comments attached to the parent value itself are captured only by Commented<Container> and are not inherited by the first child field or element. A comment inside the container, directly above a child key or element, is captured by that child.
• When an alias to a container is used as a nested value, leading comments above the alias follow the same inside-container rule. For example, root:\n # comment\n *defaults leaves the comment available to the expanded container’s first child rather than capturing it on the alias use.

Examples

Basic scalar with a comment in block style:

use serde::Serialize;

// Re-exported from the crate root
use serde_saphyr::Commented;

let out = serde_saphyr::to_string(&Commented(42, "answer".to_string())).unwrap();
assert_eq!(out, "42 # answer\n");

As a mapping value, still inline:

use serde::Serialize;
use serde_saphyr::Commented;

#[derive(Serialize)]
struct S { xn: Commented<i32> }

let s = S { xn: Commented(5, "send five starships first".into()) };
let out = serde_saphyr::to_string(&s).unwrap();
assert_eq!(out, "xn: 5 # send five starships first\n");

Important: Comments are suppressed in flow contexts (no # appears), and ignored for complex inner values during serialization. During deserialization, parent-side comments on a container such as root: # comment are captured by Commented<Container> only; comments inside the container, directly above the first child key or element, remain available to that child. The same applies to leading comments above a nested alias whose target is a container.

Tuple Fields

0: T

1: String

Trait Implementations

impl<T: Clone> Clone for Commented<T>

fn clone(&self) -> Commented<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Commented<T>

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

Formats the value using the given formatter.

impl<'de, T: Deserialize<'de>> Deserialize<'de> for Commented<T>

Available on crate feature comments only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl<T: Eq> Eq for Commented<T>

impl<T: PartialEq> PartialEq for Commented<T>

fn eq(&self, other: &Commented<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: Serialize> Serialize for Commented<T>

Available on crate feature comments only.

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl<T: PartialEq> StructuralPartialEq for Commented<T>