Nothing enforces the documentation the crate already keeps #30

Closed
opened 2026-08-15 04:17:36 +00:00 by rosa · 0 comments
Owner

src/lib.rs sets no #![warn(missing_docs)], so the documentation this crate
keeps thoroughly is kept by hand alone. A new public item arriving undocumented
would reach a release without anything objecting, and the clippy task runs
-D warnings, so the lint would hold the line in CI for free once it passes.

It does not pass yet. Seven public fields are undocumented, all of them payloads
on error variants that carry the detail a caller reads:

  • IsoAlphabeticCodeError::InvalidCode { code } at src/lib.rs:1238
  • IsoNumericCodeError::InvalidCode { code } at src/lib.rs:1260
  • ExchangeRateError::InvalidRate { rate } at src/exchange/rate.rs:528
  • ParsePairError::MissingSeparator { notation } at src/exchange/rate.rs:539
  • ParsePairError::UnknownCurrency { code } at src/exchange/rate.rs:550
  • ExchangeError::Unquoted { base, quote } — both — at
    src/exchange/table.rs:564

Each variant's own doc comment already says what it carries, so the field
comments should add precision the variant comment does not: what the value is
measured in, or which of two plausible readings it takes.

Document the seven, then turn the lint on. missing_debug_implementations is
the companion worth considering in the same pass, though every public type
already derives Debug, so that one passes today.

`src/lib.rs` sets no `#![warn(missing_docs)]`, so the documentation this crate keeps thoroughly is kept by hand alone. A new public item arriving undocumented would reach a release without anything objecting, and the `clippy` task runs `-D warnings`, so the lint would hold the line in CI for free once it passes. It does not pass yet. Seven public fields are undocumented, all of them payloads on error variants that carry the detail a caller reads: - `IsoAlphabeticCodeError::InvalidCode { code }` at `src/lib.rs:1238` - `IsoNumericCodeError::InvalidCode { code }` at `src/lib.rs:1260` - `ExchangeRateError::InvalidRate { rate }` at `src/exchange/rate.rs:528` - `ParsePairError::MissingSeparator { notation }` at `src/exchange/rate.rs:539` - `ParsePairError::UnknownCurrency { code }` at `src/exchange/rate.rs:550` - `ExchangeError::Unquoted { base, quote }` — both — at `src/exchange/table.rs:564` Each variant's own doc comment already says what it carries, so the field comments should add precision the variant comment does not: what the value is measured in, or which of two plausible readings it takes. Document the seven, then turn the lint on. `missing_debug_implementations` is the companion worth considering in the same pass, though every public type already derives `Debug`, so that one passes today.
rosa closed this issue 2026-08-15 06:22:17 +00:00
Sign in to join this conversation.
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rosa/lucre#30
No description provided.