Skip to content

Document the write diagnostics and VR mismatch in the README. - #73

Merged
xbmlz merged 1 commit into
mainfrom
readme-0.28-diagnostics
Aug 24, 2026
Merged

xbmlz merged 1 commit into
mainfrom
readme-0.28-diagnostics

Conversation

@xbmlz

@xbmlz xbmlz commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

v0.28.0 shipped two diagnostics the README never mentioned.

WriteOptions did not appear in the README at all, so the write-side hook — the
headline of #67 — was discoverable only from the changelog or godoc. The
read-side section still listed the 0.27.0 set of anomalies, with no VR
disagreement (#68), and said a diagnostic carries its "enclosing sequences",
which stopped being the whole truth when Diagnostic.Path started naming which
item of each (#69). Adding the README paragraph in the same commit as the
feature is what #54 did for read diagnostics; I missed it three times in a row.

The example changed shape because the obvious one is impossible

The changelog leads the write diagnostics with a fractional float64 in an
IS, so that is what I first wrote the README example on. It cannot happen
through the typed API:

SetFloat: godicom: tag (0018,0086) has VR IS, which does not hold
floating-point values

SetFloat rejects it at the call site, so an example written that way would
never reach the hook it was demonstrating. I checked each construction against
the real API before picking one:

construction result
SetInt(EchoNumbers, 3000000000) reaches the writer, reports is outside [-2147483648, 2147483647]
SetString(SliceThickness, "0.3333333333333333") reaches the writer, reports is 18 bytes, over the 16 a DS allows
Set(NewDataElement(EchoNumbers, VRIS, 1.5)) reaches the writer, reports "1.5" is not an integer string
SetFloat(EchoNumbers, 1.5) rejected at the call site
SetFloat(SliceThickness, 1.0/3.0) reports nothing — 0.28.0 truncates it per FormatNumberAsDS

So the example uses SetInt, the comment under it is the diagnostic's real
output byte for byte, and the section closes on the boundary that last row
implies: the dictionary-VR setters reject what they can see themselves, and the
hook covers what they cannot.

No behaviour change — README.md and a Docs: changelog entry under
Unreleased, following the v0.26.0 and v0.24.0 precedent for doc-only entries.
The three reported cases above are already pinned by write_diagnostic_test.go,
so I did not add a duplicate test; the repo has no Example functions or
README-snippet harness, and introducing one is a bigger call than this fix.

v0.28.0 added two diagnostics the README never mentioned. WriteOptions did not
appear in it at all, so the write-side hook -- the headline of the release --
was discoverable only from the changelog or godoc. The read section still
described the 0.27.0 set of anomalies and said diagnostics carry their
"enclosing sequences", which stopped being the whole truth when Diagnostic.Path
started naming which item of each.

The write example is built on SetInt past the int32 an IS allows rather than the
fractional float the changelog leads with, because SetFloat rejects a float for
an IS at the call site: an example written that way could never reach the hook
it was demonstrating. Verified each construction against the real API before
choosing -- an over-long DS string reports, and SetFloat(SliceThickness, 1/3)
now reports nothing at all, since 0.28.0 truncates it per FormatNumberAsDS.

The section closes on that boundary, because it is the thing a reader will
otherwise learn by accident: the dictionary-VR setters reject what they can see
themselves, and the hook covers what they cannot.
@xbmlz
xbmlz merged commit b616761 into main Aug 24, 2026
5 checks passed
@xbmlz
xbmlz deleted the readme-0.28-diagnostics branch August 24, 2026 03:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant