Make the README's snippets compile-checked Example functions. - #74
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 afloat for an
ISat the call site and so could never reach the hook it wasdemonstrating — I only caught it because I ran it. These four
Examplefunctions cover the same ground and go stale loudly instead of quietly:
go testcompiles them and checks their output, and pkg.go.dev renders them besidethe API they use.
ExampleExampleReadOptionsExampleWriteOptionsExampleDataset_EncodeNo fixture, no filesystem
An
Examplecannot take a*testing.T, so it has not.TempDir, and a snippetthat 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
ExampleReadOptionscut four bytes off the end andprovoke a real
truncated_valuerather than describe one:partTensets SOP Class and Instance UID because PS3.10 requires File Meta toname them —
EnforceFileFormatfills the File Meta from the dataset and refuseswithout 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:
The README comment now says what
erractually prints, andExampleWriteOptionspins 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.gois new, plus the READMEcomment fix and a
Docs:changelog entry under Unreleased.