Skip to content

Make the README's snippets compile-checked Example functions. - #74

Merged
xbmlz merged 1 commit into
mainfrom
compile-checked-readme-examples
Aug 24, 2026
Merged

xbmlz merged 1 commit into
mainfrom
compile-checked-readme-examples

Conversation

@xbmlz

@xbmlz xbmlz commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

Follow-on to #73, which fixed the README by hand and showed why hand is not
enough.

The README's Go snippets have no compiler behind them. That is exactly how the
write-diagnostic example in #73 came to be written on SetFloat, which rejects a
float for an IS at the call site and so could never reach the hook it was
demonstrating — I only caught it because I ran it. These four Example
functions cover the same ground and go stale loudly instead of quietly: go test compiles them and checks their output, and pkg.go.dev renders them beside
the API they use.

Example README snippet
Example set a value, encode, read it back
ExampleReadOptions the read diagnostic hook
ExampleWriteOptions the write diagnostic hook
ExampleDataset_Encode dataset bytes with no File Meta

No fixture, no filesystem

An Example cannot take a *testing.T, so it has no t.TempDir, and a snippet
that opens a path the reader does not have teaches less than one that builds its
own bytes. Each example encodes a Part 10 dataset in memory and reads it back.
That is also what lets ExampleReadOptions cut four bytes off the end and
provoke a real truncated_value rather than describe one:

truncated_value at (0010,0010): need 8, have 4
PatientName present: false

partTen sets SOP Class and Instance UID because PS3.10 requires File Meta to
name them — EnforceFileFormat fills the File Meta from the dataset and refuses
without them. Worth a reader seeing once, so it is a commented helper rather
than hidden.

And it found one more README error

The write example's comment showed the diagnostic's own message, but a caller
gets it wrapped:

godicom: error writing dataset: godicom: invalid_value at (0018,0086) IS: ...

The README comment now says what err actually prints, and ExampleWriteOptions
pins it.

Gates run locally before pushing: gofmt -l (via the CRLF-safe copy), go build ./..., go vet ./..., go test ./..., and staticcheck -checks=all —
all clean. No non-test code changes; example_test.go is new, plus the README
comment fix and a Docs: changelog entry under Unreleased.

The README's Go snippets had no compiler behind them. That is how the write
diagnostic example came to be written on SetFloat, which rejects a float for an
IS at the call site and could never reach the hook it was demonstrating. These
four Examples cover the same ground and go stale loudly: go test compiles them,
checks their output, and pkg.go.dev renders them next to the API they use.

They take no fixture path and touch no filesystem. An Example has no *testing.T
and so no t.TempDir, and a snippet that opens a file the reader does not have
teaches less than one that builds its own bytes -- so each encodes a Part 10
dataset in memory and reads it back, which also makes ExampleReadOptions able to
truncate those bytes and provoke a real diagnostic rather than describe one.

partTen sets SOP Class and Instance UID because PS3.10 requires File Meta to
name them, not as ceremony: EnforceFileFormat fills the File Meta from the
dataset and refuses without them, which is worth a reader seeing once.

Writing them found one more README error. The write example's comment showed the
diagnostic's own message, but the caller gets it wrapped in "error writing
dataset"; the comment now says what err actually prints.
@xbmlz
xbmlz merged commit f17c828 into main Aug 24, 2026
5 checks passed
@xbmlz
xbmlz deleted the compile-checked-readme-examples branch August 24, 2026 03:57
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