📖 2 min read (~ 300 words).

Comments

Round trip

Ask the decoder to fill a CommentMap, then hand the same map to the encoder:

cm := codec.CommentMap{}

var v map[string]any
if err := codec.UnmarshalWithOptions(src, &v, codec.CommentToMap(cm)); err != nil {
	// ...
}

out, err := codec.MarshalWithOptions(v, codec.WithComment(cm))

Given

# head of doc
name: x   # line on name
# head of ports
ports:
  - 80

the map holds

$.name    Head  [" head of doc"]
$.name    Line  [" line on name"]
$.ports   Head  [" head of ports"]

and the re-encode writes all three back.

What the key is

A YAMLPath string, and the same syntax expressions.PathString takes. Two comments on one path do not collide: the entry is a slice, and each *codec.Comment carries its own CommentPosition — CommentHeadPosition, CommentLinePosition or CommentFootPosition.

codec.HeadComment, LineComment and FootComment build them, which is how you add a comment to a document that had none.

A leading comment belongs to the first key

# head of doc sits above the whole document, and it comes back as the head comment of $.name. There is no key for the document itself.

Paths have to be on

The map is keyed by the node paths the parser records. parser.WithOmitNodePaths stops recording them, and the map then comes back keyed by empty strings, with no error. See the parser.

On the tree instead

parser.WithComments keeps comments on the tree, as ast.CommentNode and ast.CommentGroupNode, reachable through ast.Node.GetComment. That is the layer to use when the comments matter as much as the values — a CommentMap is a projection, and the tree is the document.