Comments
Round trip
Ask the decoder to fill a CommentMap, then hand the same map to the encoder:
Given
the map holds
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.