fix: a mark is not a substitute for a docstring, and the docs examples now run

[sotashimozono]

Two findings from the registration review, both still live in main until this lands.

1. A marked public name with no docstring passed the audit clean

Measured before changing anything:

module Looser
public marked_only
@experimental "shape not settled" marked_only(x) = x   # no docstring
end

julia> audit(Looser).unaccounted
Symbol[]        # ← passes

That is the looser practice the review objected to, and the objection was narrow and correct — the design itself was called "a perfectly fine idea". The only thing being argued against was letting a mark stand in for prose.

Audit gains undocumented: public, own, no docstring, mark or not. test_surface asserts that empty, so a marked name with no prose fails exactly as an unmarked one does.

bucket	meaning
documented	has a docstring
declared	has a mark — an additional account, never a substitute
undocumented	no docstring, marked or not — what test_surface asserts empty
unaccounted	neither account at all — a subset of undocumented

There is deliberately no require_docstring switch, though test/spec/ asked for one. A knob that turns the rule off wholesale is the thing being objected to. skip is the escape: per-name, visible, and it can only shrink. The spec entry was rewritten to assert no such kwarg exists rather than deleted.

The Clean fixture in test_ext.jl stopped being clean, because it carried the mark and no prose. The fixture moved, not the rule.

2. The trailing-backslash continuations were never fixed

Reported in the review on 2026-09-02 in eleven places. Eight were still there, unchanged since the initial commit — #4 did not touch them. Reproduced verbatim:

ArgumentError: @experimental: nothing to mark — give a definition or a name

All eight now use the parenthesised call form, checked to work for both the attached definition and the name-list subject:

@experimental(
    "signature will be wrapped once the write-back refactor settles",
    function ingest(config; doc, kwargs...)
        # ...
    end,
)

The review suggested jldoctest as the guard. It would not have caught this: \ parses as left-division, so the block is syntactically valid and fails only at macro expansion — a doctest would have had to run it, and most blocks reference a MyPackage that does not exist. The guard added instead is a lint over every ```julia fence in the README, docs/src/ and `src/`, for the character itself. Confirmed by reintroducing one and watching it report `README.md:126`.

The one remaining trailing \ is in src/release.jl, inside a triple-quoted string, where it is a legitimate string continuation.

Also

docs/src/adopting.md framed the two accounts as a choice — "it is settled → write the docstring; it is not settled → say so". It now says the docstring is owed either way, and the mark is what a docstring cannot carry: a machine reads it, so a run that goes through the name says so.

Suite: 540 pass, 149 broken, 0 failing.

🤖 Generated with Claude Code

[github-actions]

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

(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!