Repository navigation
fix: render macro-generated items from rustdoc JSON - #421
Merged
Merged
Conversation
- A macro call's span names no item, so the surface listed the call - Fingerprint hashes the rendered declaration and docs, never JSON ids
Verdenroz
added
soothfast:merge
Contributor
soothfast gatesoothfast-registry |
Contributor
soothfast gatesoothfast-report |
Contributor
soothfast gatesoothfast-measure |
Contributor
soothfast gatesoothfast-docs |
Contributor
soothfast gatesoothfast-site |
Contributor
soothfast gatesoothfast-sdk |
Contributor
soothfast gatesoothfast-spec |
Verdenroz
added
soothfast:merge
This branch was successfully deployed
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.
What changed
A public item generated by a
macro_rules!invocation now appears in the API surface under its own name, with a declaration rebuilt from its rustdoc JSON item. Its fingerprint is taken from that declaration and its doc comment. Closes #364.Why
rustdoc gives a macro-generated item the span of the macro call. The surface took the declaration from the span text up to the first
{or;, so every such item rendered as the call, for example a headingdefine_batch_response! { }with no body, and the item's real name appeared nowhere. The fingerprint was the call-site text as well, so editing the macro body changed the generated item without marking it as changed.An item whose span is its own declaration takes the path it took before, and its fingerprint and signature are unchanged.
How was this tested
cargo fmt --all -- --check: passed.cargo clippy --workspace --all-targets -- -D warnings: passed.cargo soothfast test --all-features: 3 of 11 packages selected, 5 binaries run, 0 failed.cargo test -p soothfast-docs surface: 26 passed. The 18 existing surface tests pass unchanged, and a new one pins an ordinary struct's fingerprint tofnv1aof its normalized span text.docs referenceon a crate whose items come from two macros, against real rustdoc JSON. It renderedpub struct BatchQuotes { pub quotes: Vec<String> },pub enum Kind { A, B },pub struct Pair(pub u8, pub String)andpub const fn free(x: &mut i32) -> i32, each with its doc comment, and left an ordinary struct as it was.git diff origin/master -- soothfast.lock soothfast-gate.lockis empty.What the rebuilt declaration leaves out: generic bounds and where clauses, enum variant payloads, and the types of constants, statics and aliases. Types it cannot render (
dyn,impl, raw and function pointers, qualified paths) print as_. An invocation that names the item inside its own parentheses, such asmake!(Foo);, is still treated as a declaration and renders as the call.Checklist
make checkpasses (fmt, clippy-D warnings,cargo test --workspace)make gate BASE=masterpasses, or any intentional cost change is explained above///doc commentsREADME.md,docs/,soothfast:bind/soothfast:claimmarkers) updated if behavior changed