Skip to content

Fix stale Rust API references in documentation examples#238

Merged
dchud merged 1 commit into
mainfrom
docs/fix-stale-rust-examples
May 29, 2026
Merged

Fix stale Rust API references in documentation examples#238
dchud merged 1 commit into
mainfrom
docs/fix-stale-rust-examples

Conversation

@dchud
Copy link
Copy Markdown
Owner

@dchud dchud commented May 29, 2026

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 compiled examples/, and verified by compiling a throwaway example exercising every shape (since mkdocs can't compile the fences itself):

  • Fieldfield.get_subfield('a') (method, char) for field.subfield("a"); tag/indicator1/indicator2/subfields are public fields (no parens); field.value() not field.data().
  • Recordget_field(tag) not field(tag); get_control_field(tag) not control_field(tag); record.leader is a public field.
  • Query DSLFieldQuery::new().tag(...) + record.fields_matching(&q) (no static FieldQuery::tag, no query.find_all); tag_range(...) + fields_matching_range; with_subfield(...)SubfieldValueQuery + fields_matching_value.
  • BuilderRecord::builder(leader) (no .leader()); Leader::from_bytes(...) (no Leader::default()); control_field_str/subfield_str for literals; Field::builder("245".to_string(), …).
  • Format conversionmrrc::json::record_to_json / mrrc::marcxml::record_to_marcxml / mrrc::marcjson::record_to_marcjson (+ inverses), not the nonexistent mrrc::formats::{to_json, …}.
  • Added use mrrc::RecordHelpers; wherever record.title() is used; fixed the testing.md Option<&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.sh green (566 tests + doctests + mkdocs). CHANGELOG [Unreleased] credits @acdha.

Closes #233

Bead: bd-nj22

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>
@dchud dchud self-assigned this May 29, 2026
@dchud dchud merged commit 640ce9d into main May 29, 2026
@dchud dchud deleted the docs/fix-stale-rust-examples branch May 29, 2026 03:45
dchud added a commit that referenced this pull request May 29, 2026
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;
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this supposed to be showing how to use SubfieldPatternQuery rather than a regular Rust regex?

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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') {
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix stale Rust API references in documentation examples

2 participants