Fix stale Rust API references in documentation examples#238
Conversation
The Rust code examples across the docs referenced methods and call shapes that don't match the real API, so most wouldn't compile. They drifted because rustdoc doctests run in CI but mkdocs Markdown fences are never compiled. Reported by @acdha. Corrected against src/ and the compiled examples/, verified by compiling a throwaway example exercising every shape: - Field: `field.get_subfield('a')` (method, char arg) for the old `field.subfield("a")`; `tag` / `indicator1` / `indicator2` / `subfields` are public fields (no parens); `field.value()` not `field.data()`. - Record: `get_field(tag)` not `field(tag)`; `get_control_field(tag)` not `control_field(tag)`; `record.leader` is a public field. - Query DSL: `FieldQuery::new().tag(...)` builder + `record.fields_matching(&q)` (no static `FieldQuery::tag`, no `query.find_all`); `tag_range(...)` + `fields_matching_range`; `with_subfield(...)` → `SubfieldValueQuery` + `fields_matching_value`. - Builder: `Record::builder(leader)` (leader is an arg, no `.leader()`); `Leader::from_bytes(...)` (no `Leader::default()`); `control_field_str` / `subfield_str` for string literals; `Field::builder("245".to_string(), ...)`. - Format conversion: `mrrc::json::record_to_json` / `mrrc::marcxml::record_to_marcxml` / `mrrc::marcjson::record_to_marcjson` (and their `*_to_record` inverses), not the nonexistent `mrrc::formats::{to_json, ...}`. - `use mrrc::RecordHelpers;` added wherever `record.title()` is used. - testing.md: `title()` returns `Option<&str>`, so the assert uses `Some("Test Title")` not `Some("Test Title".to_string())`. Out of scope (follow-up): the rust-api.md prose "Key Methods" reference tables (method-call notation + some wrong return types) and a couple of Python-fence stale refs. Reported by @acdha (#233). Closes #233 Bead: bd-nj22 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Last v0.8.1 @acdha reward item. Follow-up bd-du5n filed for the rust-api.md reference tables + Python-fence refs (under docs epic bd-c7ok). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| Match subfield values with patterns: | ||
|
|
||
| ```rust | ||
| use mrrc::SubfieldPatternQuery; |
There was a problem hiding this comment.
Isn't this supposed to be showing how to use SubfieldPatternQuery rather than a regular Rust regex?
There was a problem hiding this comment.
Fixed in #239. That section now uses SubfieldPatternQuery::new("020", 'a', r"^97[89]") with record.fields_matching_pattern(&query) instead of the raw regex::Regex loop.
| // Partial match (contains) | ||
| for field in record.fields_by_tag("650") { | ||
| if let Some(subject) = field.subfield("a") { | ||
| if let Some(subject) = field.get_subfield('a') { |
There was a problem hiding this comment.
This still isn't using SubfieldValueQuery or partial matching. I'd think this would be more:
let query = SubfieldValueQuery::partial("650", 'a', subject);
if (query.matches(&field)) …(except that might be record.fields_matching for performance)
There was a problem hiding this comment.
Fixed in #239. It now uses SubfieldValueQuery::new("650", 'a', "History") for exact matches and SubfieldValueQuery::partial("650", 'a', "History") for substring matches, both via record.fields_matching_value(&query); the section also notes query.matches(&field) for testing a single field. Your suggested shape was right.
The Rust code examples across the docs referenced methods and call shapes that don't match the real API, so most wouldn't compile. Root cause: rustdoc doctests run in CI, but mkdocs Markdown fences are never compiled, so the drift went unnoticed. Reported by @acdha.
Every Rust fence across 11 files (quickstart, tutorials, reference) was corrected against
src/and the compiledexamples/, and verified by compiling a throwaway example exercising every shape (since mkdocs can't compile the fences itself):field.get_subfield('a')(method, char) forfield.subfield("a");tag/indicator1/indicator2/subfieldsare public fields (no parens);field.value()notfield.data().get_field(tag)notfield(tag);get_control_field(tag)notcontrol_field(tag);record.leaderis a public field.FieldQuery::new().tag(...)+record.fields_matching(&q)(no staticFieldQuery::tag, noquery.find_all);tag_range(...)+fields_matching_range;with_subfield(...)→SubfieldValueQuery+fields_matching_value.Record::builder(leader)(no.leader());Leader::from_bytes(...)(noLeader::default());control_field_str/subfield_strfor literals;Field::builder("245".to_string(), …).mrrc::json::record_to_json/mrrc::marcxml::record_to_marcxml/mrrc::marcjson::record_to_marcjson(+ inverses), not the nonexistentmrrc::formats::{to_json, …}.use mrrc::RecordHelpers;whereverrecord.title()is used; fixed thetesting.mdOption<&str>assert.This also resolves the "loop structure oddities" on the query page (mixed
find_all/hand-rolled loops → coherent examples).Scope note / follow-up: filed a separate bead for the rust-api.md prose "Key Methods" reference tables (method-call notation + a few wrong return types) and two Python-fence stale refs — distinct from the Rust examples this bead targets.
.cargo/check.shgreen (566 tests + doctests + mkdocs). CHANGELOG[Unreleased]credits @acdha.Closes #233
Bead: bd-nj22