Crate explainable 

explainable

A zero-overhead educational layer for Rust libraries.

This crate defines the traits and types that any domain crate can implement to give its users a step-by-step, pedagogical view of an operation chain — text explanations, before/after visuals, or both — without touching the domain’s hot path.

Architecture

Three interfaces make up the system:

Trait	Implemented by	Purpose
ExplainDisplay	Domain crate	Opaque rendering surface
RenderVisual	Domain crate	Produces a before/after ExplainDisplay
Explainable	Domain crate	Opts a type into the system (one line)

The #[explainable] attribute macro annotates operation trait definitions in the domain crate. For every method in the trait it generates a matching method on Explaining<T> that snapshots inner before the call, calls through to the real operation, captures after, and accumulates an Explanation.

Quick start

// Domain crate --- opt in
#[explainable]
pub trait MyOperations {
    fn some_operation(&self) -> Result<Self, MyError>;
}

impl MyOperationsExplainText for MyType {
    fn explain_text_some_operation(before: &Self, after: &Self) -> String {
        format!("Did the thing. Value went from {} to {}.", before, after)
    }
}

impl RenderVisual for MyType { /* ... */ }
impl Explainable for MyType {}

// User --- one extra call to open an explaining chain
use my_crate::MyOperationsExt; // bring the extension trait into scope

let (result, _explanations) = value
    .explaining(ExplainMode::Both)
    .some_operation()
    .explain();

Overhead model

The hot path is completely unaffected. Explanation machinery activates only when .explaining() is called. Every existing call site remains valid and untouched.

Structs

Explaining

An explaining chain wrapping a value of type T.

Explanation

A single accumulated explanation for one operation in an explaining chain.

Enums

ExplainMode

Controls which kinds of explanation are produced for each operation in a chain.

Traits

ExplainDisplay

An opaque rendering surface for a single visual explanation.

Explainable

Marker trait that opts a type into the explaining system.

RenderVisual

Implemented by a domain type to supply before/after visual explanations.

Attribute Macros

explainable

Annotate an operation trait to generate the full explaining scaffolding for every method in that trait.