10. Comments
Readable Object Notation

; starts a line comment at the beginning of a line or after whitespace. The comment continues to the end of the line. A document must not mix ; comments with an explicit $comment member. Within a quoted string, or within a bare word rather than after whitespace, the same characters are text. A semicolon within an unbroken token remains text.

Comments are preserved in a map's $comment string instead of being discarded during parsing. Comment lines are joined with newlines. Prefixes record where each comment appeared:

Position Stored text
At the start of a map text
After a member or list item name: text
Before a later member or list item name:: text
At the end of a map :: text

For a list stored in a map, the prefix includes the member name and a zero-based item index, such as fields[0]. Comments inside a nested map are stored in that map's $comment member.

RON
; A person
name Ada ; Display name
→
Canonical RON
; A person
name Ada ; Display name
→
{} JSON
{
  "$comment": "A person\nname: Display name",
  "name": "Ada"
}

Comments can also follow list items or appear on separate lines between them.

RON
fields [
  id ; identifier
]
→
Canonical RON
fields [
  id ; identifier
]
→
{} JSON
{
  "$comment": "fields[0]: identifier",
  "fields": [
    "id"
  ]
}

With epsilon convert --comment-roundtrip, comments use structured JSON Pointer groups in the $comment string. The start and end groups distinguish value occurrences from collection opening and closing boundaries. Root lists use reserved comment-only objects in the JSON array; root scalars use a marker and the value. Ordinary JSON conversion keeps $comment strings as fields.