#18

README.md

@@ -614,14 +614,14 @@ if (!result.HasErrors()) {
 | --- | --- |
 | `Error` / `FileOpenError` | Input cannot be opened |
 | `Error` / `FileReadError` | Input cannot be read completely |
-| `Error` / `InvalidStatement` | Invalid frame/signal definition, duplicate, or payload violation |
+| `Error` / `InvalidStatement` | Invalid frame/signal definition or comment, unresolved comment reference, duplicate, or payload violation |
 | `Error` / `InvalidValueDescription` | Invalid `VAL_` syntax, duplicate value, or unresolved reference |
 | `Error` / `InvalidMultiplexing` | Selector, branch range, or signal overlap validation failed |
 | `Warning` / `UnsupportedStatement` | Unregistered statement skipped; decoding or metadata may be incomplete |
 | `Error` / `UnsupportedStatement` | Extended multiplexing (`SG_MUL_VAL_`) rejected |
 
 Parsing stops at the first error and returns an empty database, together with
-any preceding warnings and the error. Deferred `VAL_` and multiplexing errors
+any preceding warnings and the error. Deferred comment, `VAL_`, and multiplexing errors
 retain their original source lines. Invalid signal markers use `InvalidStatement`.
 `HasErrors()` checks severity; warnings alone do not make a parse fail.
 
@@ -637,8 +637,9 @@ indentation, even when they name unsupported syntax. Frame, signal, bus, and
 node definitions or a line with arguments end the list. Actual unsupported
 statements outside that list are reported.
 Node and bus metadata are not stored. Other comment forms (`CM_`, `CM_ BU_`,
-`CM_ EV_`) are ignored by the comment handler; comments only attach to already
-parsed frames/signals. Supported statements currently require one physical line.
+`CM_ EV_`) are ignored by the comment handler. Frame and signal comments may span
+physical lines and resolve after definitions are read; other supported statements
+require one physical line.
 
 `ParseFile(path)` remains compatible: it returns the database, discards warnings,
 and throws `std::runtime_error` on the first error with the existing `path:line:`
@@ -819,6 +820,19 @@ Stored in:
 - `FrameInfo::comment`
 - `SignalInfo::comment`
 
+Comments accept spaces and tabs between fields, escaped quotes (`\"`) and
+backslashes (`\\`), and text spanning multiple physical lines. Newlines, blank
+lines, and indentation inside quoted text are preserved; CRLF becomes LF.
+Comments may appear before their frame or signal definitions. References use the
+same decimal CAN ID validation and normalization as `BO_`, including reserved-bit
+and overflow checks and distinct standard/extended targets. Repeated comments
+apply in statement order, so the last comment wins, including empty text.
+
+Malformed supported comments (including invalid escapes, missing quotes or
+semicolon, and trailing text) and missing frame/signal references produce an
+`InvalidStatement` error at the comment's starting line. Failed parses return an
+empty database; `ParseFile` throws with the same source location.
+
 ---
 
 ## CAN ID Normalization
@@ -1149,7 +1163,8 @@ Additional behavior to account for:
   databases are also checked for ambiguous `VAL_` references during resolution
 - payload lengths are checked against storage bounds (`0..255`), rather than
   CAN or CAN FD protocol limits
-- comment handling is limited to the supported forms and already parsed targets
+- comment handling is limited to frame and signal comments; references resolve
+  after definitions are read
 
 Motorola extraction uses DBC sawtooth numbering: a start bit of 7 traverses
 `7..0, 15..8, 23..16`. Regression tests cover aligned and unaligned signals,