fix: the documentation's examples run, and two bugs they exposed

[sotashimozono]

A review before resubmitting. Running every self-contained block under docs/src turned up two defects in shipped code, not only in prose.

Closes #16, #17, #18, #19.

record swallowed the caller's exception — #16

On the default path:

julia> ExperimentalAPI.record(() -> error("the caller's own message"))
ERROR: rethrow(exc) not allowed outside a catch block

Base.rethrow(err) is legal only inside a catch. Outside one it raises its own ErrorException and the original is lost.

The existing test passed the whole time. @test_throws ErrorException ExperimentalAPI.record(() -> error("boom")) is satisfied by ErrorException("rethrow(exc) not allowed outside a catch block") — it pinned the exception type while the caller was getting a different exception entirely. The new test pins the message, with a control asserting the old one is absent.

stamp(path) do … end had no method — #17

do passes the function first; the methods took the path first, so the form the documentation teaches raised MethodError. record already takes the function first, so the two verbs disagreed as well.

The documentation called unexported names unqualified — #18, 29 sites

Only @experimental is exported. record, audit, mark, compare, stamp, … are public and not exported, so every one of those blocks is UndefVarError for a reader who wrote using ExperimentalAPI — which is what the examples above them show.

api.md states the convention the pages were breaking:

experimental is public, not exported, so it is qualified.

The front page still had the reviewed defect — #19

docs/src/index.md opened with energy(m::Model) = m.β * correction(m), neither defined. That is what the registration review named for the README; it was fixed there (#11) and not here.

It is now self-contained and an @example block, so Documenter runs it during the build:

┌ Error: failed to run `@example` block in docs/src/index.md:14-20
│    UndefVarError: `Model` not defined in `Main.__atexample__named__frontpage`

That is the reviewer's suggested guard, on the block that needs it most — stronger than the bespoke executor, because it is the tool's own mechanism.

What now checks the rest

test/test_readme.jl executes every self-contained block under docs/src. Illustrative blocks are skipped through an explicit list of the placeholders the documentation asks the reader to supply, so a block needing a new one fails by name rather than being silently skipped. A control asserts at least five blocks survive the filter, and that the front page is still an @example.

doctest = true, with one jldoctest in observing.md. Only one, and the page says why rather than leaving it implied: the error block would carry LoadError and an absolute-path stacktrace, and the Entry display prints its module — in Documenter's sandbox that is not Main, so a doctest of it would show a line no reader ever sees at their own REPL.

Not in this change

#20 — two placeholder tracking = URLs (github.com/org/Pkg.jl/issues/12) return 404, while the package's own tests use example.invalid. Filed rather than folded in.

Suite: 990 passed.

🤖 Generated with Claude Code

[github-actions]

📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR14/

(updates on each push to this PR)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!