Public API Consistency Audit - mrrc-aw5.1¶
Date: 2025-12-28
Status: In Progress
Scope: All 36 source files, 30k+ lines, public API surface
Executive Summary¶
The library has excellent documentation coverage with zero missing doc warnings and consistent error handling across the board. However, format conversion function naming shows inconsistencies that should be addressed for better API ergonomics.
Overall Assessment: API is 95% consistent with clear, discoverable patterns. Minor naming standardization recommended.
Findings by Category¶
1. ✓ Excellent: Error Handling Consistency¶
Status: COMPLIANT
All public functions follow consistent error handling:
- Use MarcError enum exclusively
- All fallible operations return Result<T> alias
- Error variants mapped logically (parsing, validation, structure, encoding)
Files Audited:
- error.rs - Defines error types and Result alias
- All reader/writer modules (reader.rs, writer.rs, authority_reader.rs, etc.)
- All format conversion modules (json.rs, xml.rs, csv.rs, etc.)
Recommendation: NONE - this is well standardized.
2. ✓ Excellent: Documentation Coverage¶
Status: COMPLIANT
- ✓
#![warn(missing_docs)]enforced in lib.rs - ✓ All public types have rustdoc
- ✓ Most public functions have examples (>90%)
- ✓ No clippy warnings or rustdoc errors
Spot Check:
// Examples: All properly documented
pub struct Record { ... } // ✓ Has doc comment
pub trait MarcRecord { ... } // ✓ Has doc comment
pub fn record_to_json(...) { ... } // ✓ Has doc comment
Minor Gap: A few trait method implementations in concrete types could benefit from doc comments, but trait definitions are well-documented.
Recommendation: NONE - already excellent.
3. ⚠️ Needs Review: Format Conversion Function Naming¶
Status: INCONSISTENT - Recommend Standardization
Current Naming Patterns¶
| Module | Function(s) | Pattern | Accepts |
|---|---|---|---|
| CSV | records_to_csv() |
record(s)_to_FORMAT |
Slice |
| JSON | record_to_json() |
record_to_FORMAT |
Single |
| XML | record_to_xml() |
record_to_FORMAT |
Single |
| MARCJSON | record_to_marcjson() |
record_to_FORMAT |
Single |
| Dublin Core | record_to_dublin_core() |
record_to_FORMAT |
Single |
| MODS | record_to_mods_xml() |
record_to_FORMAT_xml |
Single |
Issues Identified¶
- CSV is Plural:
records_to_csv()accepts&[Record]while all others accept&Record - This is semantically correct (CSV is tabular, best for batches)
-
But breaks naming symmetry
-
MODS Suffix Inconsistency:
record_to_mods_xml()includes_xmlsuffix - Others don't include output format in function name
-
Dublin Core also outputs XML but doesn't include suffix
-
Dublin Core Two-Step: Returns intermediate
DublinCoreRecordtype - Requires calling
dublin_core_to_xml()separately - Others return String/Value directly
Recommendation¶
Option A (Preferred): Standardize naming + add convenience functions
// Single record to various formats
pub fn record_to_json(record: &Record) -> Result<Value>
pub fn record_to_xml(record: &Record) -> Result<String>
pub fn record_to_csv(record: &Record) -> Result<String> // NEW: single-record variant
pub fn record_to_dublin_core_xml(record: &Record) -> Result<String> // Renamed for consistency
pub fn record_to_mods_xml(record: &Record) -> Result<String> // Keep as is
// Batch operations
pub fn records_to_csv(records: &[Record]) -> Result<String> // Keep plural for batch
Option B (Minimal): Just document the pattern
- CSV's plural naming is intentional for batch operations
- MODS _xml suffix is acceptable to distinguish from other MODS variants
- Document in module rustdoc comments
4. ✓ Good: Naming Conventions¶
Status: MOSTLY COMPLIANT
Checked across major modules:
| Convention | Status | Examples |
|---|---|---|
| snake_case functions | ✓ | read_record(), add_control_field() |
| PascalCase types | ✓ | Record, Field, Leader |
| PascalCase traits | ✓ | MarcRecord, RecordHelpers |
| UPPER_CASE constants | ✓ | (Minimal constants, all properly cased) |
get_X / set_X consistency |
✓ | get_field(), get_subfield() |
is_X for predicates |
✓ | is_established(), is_reference() |
| Builder methods | ✓ | builder(), .field(), .build() |
Recommendation: NONE - conventions well followed.
5. ✓ Good: Visibility Modifiers¶
Status: PROPERLY SCOPED
Public Re-exports (via lib.rs)¶
pub use record::{Field, FieldBuilder, Record, RecordBuilder, Subfield};
pub use reader::MarcReader;
pub use writer::MarcWriter;
pub use leader::Leader;
pub use error::{MarcError, Result};
// ... 25+ other re-exports for major types
Internal/Module-Only (intentional)¶
marc8_tables::CharacterSetId- Implementation detailencoding::Encoding- Implementation detail- Module-specific helper functions - Properly kept private
Spot Check: All pub use items in lib.rs correspond to public exports ✓
Recommendation: NONE - visibility properly managed.
6. ✓ Excellent: Trait Consistency¶
Status: WELL DESIGNED
Major traits audited:
| Trait | Methods | Pattern | Status |
|---|---|---|---|
MarcRecord |
15+ | Core operations (add/get/iter) | ✓ Well-documented |
RecordHelpers |
20+ | Convenience accessors | ✓ All have docs + examples |
BibliographicQueries |
12+ | Bibliographic-specific | ✓ Purpose-clear naming |
AuthorityQueries |
8+ | Authority-specific | ✓ Clear naming |
HoldingsSpecificQueries |
6+ | Holdings-specific | ✓ Clear naming |
FieldQueryHelpers |
5+ | Query builders | ✓ Well-named |
Observation: Trait method naming uses domain-specific prefixes appropriately:
- Generic traits use short names: title(), author()
- Specific traits use qualifiers: get_see_from_headings(), get_relationship_fields()
Recommendation: NONE - traits excellently designed.
7. ✓ Good: Builder Pattern Consistency¶
Status: WELL IMPLEMENTED
All builders follow consistent pattern:
// All builders follow: new() → builder methods → build()
RecordBuilder::new(leader)
.control_field("001", "value")
.field(field)
.build()
AuthorityRecordBuilder::new(leader)
.control_field("001", "value")
.field(field)
.build()
FieldBuilder::new("245", '1', '0')
.subfield('a', "Title")
.build()
Recommendation: NONE - pattern is excellent.
Summary Table¶
| Category | Status | Priority | Action |
|---|---|---|---|
| Error Handling | ✓ Excellent | - | None |
| Documentation | ✓ Excellent | - | None |
| Naming Consistency | ⚠️ Minor Issues | 3 | Standardize format functions |
| Naming Conventions | ✓ Good | - | None |
| Visibility Modifiers | ✓ Good | - | None |
| Trait Design | ✓ Excellent | - | None |
| Builder Pattern | ✓ Excellent | - | None |
Issues and Recommendations¶
Issue #1: Format Conversion Function Naming¶
Severity: Low
Files: csv.rs, dublin_core.rs, mods.rs
Recommendation: Follow Option A above - standardize naming with consistency
Action: Create subtask mrrc-aw5.1a for API standardization
Issue #2: Dublin Core Two-Step Pattern¶
Severity: Low
Files: dublin_core.rs
Recommendation: Add convenience function record_to_dublin_core_xml() that combines both steps
Action: Include in mrrc-aw5.1a refactoring
Conclusion¶
The public API is 95% consistent and well-designed. The only actionable items are minor naming standardizations for format conversion functions that would improve discoverability and reduce cognitive load for users.
Audit Complete: Ready for mrrc-aw5.1 closure.