Skip to content

Docs accuracy: fix fabricated and stale claims across rustdoc and READMEs #449

Description

@RAprogramm

Three audits (README.template.md, README.ru.md/README.ko.md, rustdoc prose) found the following. Fix docs to match actual behavior.

Fabrications

  • README.template.md:581 — AppError::with_retry_after_duration(...) doesn't exist (only with_retry_after_secs on AppError; with_retry_after_duration is on ErrorResponse). Snippet doesn't compile. Also stale in src/lib.rs doc.
  • README.template.md:504 — request_ref::<TelemetrySnapshot> through AppError converted via #[app_error] panics: the generated From impl discards the domain error (see #[app_error] From conversion drops source and telemetry #452-followup issue).
  • README.template.md:593-630 — DisplayMode advertised as controlling Display output; Display for Error never consults it (see followup issue).
  • src/convert/redis.rs:24 — rust,ignore example asserts AppErrorKind::Cache for an IO error; actual mapping promotes to DependencyUnavailable.
  • src/app_error/core/introspection.rs:277 — downcast_mut documented as functional; body is unconditionally None (see followup issue).
  • src/lib.rs:70 + README.template.md:89,138 — feature telegram-webapp-sdk doesn't exist; actual feature is init-data (crate init-data-rs).

Stale

  • src/lib.rs:49 — MSRV 1.90 → 1.96.
  • Five convert modules (serde_json, teloxide, init_data, redis, multipart) claim 'original error string preserved in message'; since Context refactor the message is None and text goes to metadata/source.
  • src/convert/actix.rs — claims empty-body mode without serde_json; no such path (actix feature hard-wires serde_json).
  • src/convert/init_data.rs:23 — apostrophe fences instead of backticks; example never renders/compiles.
  • src/app_error/core/backtrace.rs:98,125 — doc examples cfg(test)-guarded, never compiled; private-path imports.
  • src/response.rs:15 — gRPC wire fields are grpc.name/grpc.value, not grpc.code.
  • README.template.md:705 — 'all examples include comprehensive tests': only axum-rest-api has tests.
  • README.template.md:91 — turnkey 'tracing instrumentation': no tracing code in src/turnkey/.

Imprecise (see audit for full list, ~15 items)

  • 'everything off by default' (default = ["std"]); request_ref snippets need nightly (undocumented); sqlx feature maps sqlx_core::Error; axum enables dep:serde_json but not the serde_json feature; reqwest impl-doc contradicts module-doc on status mapping; downcast_ref downcasts the source, not the error; AppCode::try_new underscore rules; 'redacts when marked private' wording on axum/actix impls; etc.

README.ru.md / README.ko.md (~4 minor versions behind)

  • version 0.24.19 → 0.28.0 (2 places each); telegram-webapp-sdk → init-data in install snippet; add colored to snippet; MSRV badge/footer 1.90 → 1.96; license 'MIT OR Apache-2.0' → MIT (badge + footer); add missing Examples section + TOC entry; add REUSE badge.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions