🦆 waddling-errors

Core library for the Waddling Diagnostic Protocol (WDP).

What This Library Provides

• Core types: Code<C, P>, Severity, ComponentId, PrimaryId traits
• Doc generation: HTML, JSON, and catalog renderers
• Catalog formats: Full, Compact, Minimal (WDP Part 9a compliant)
• Custom renderers: Implement Renderer trait for your own formats
• Role-based filtering: Control what documentation each audience sees

For an easier API with compile-time validation, see waddling-errors-macros. The macros let you define your own module structure—components, primaries, sequences are just conventions, not requirements.

Installation

[dependencies]
waddling-errors = "0.7"

For documentation generation:

waddling-errors = { version = "0.7", features = ["doc-gen"] }

Core Usage

Define components and primaries, then create codes:

use waddling_errors::{Code, ComponentId, PrimaryId};

#[derive(Debug, Copy, Clone)]
enum Component { Auth }

impl ComponentId for Component {
    fn as_str(&self) -> &'static str { "Auth" }
}

#[derive(Debug, Copy, Clone)]
enum Primary { Token }

impl PrimaryId for Primary {
    fn as_str(&self) -> &'static str { "Token" }
}

const EXPIRED: Code<Component, Primary> = Code::error(Component::Auth, Primary::Token, 1);

println!("{}", EXPIRED.code());  // E.Auth.Token.001

Documentation Generation

Generate HTML docs, JSON, or WDP-compliant catalogs:

use waddling_errors::doc_generator::{DocRegistry, HtmlRenderer, JsonRenderer, CatalogRenderer};

let mut registry = DocRegistry::new("my_project", "1.0.0");

// Register errors, components, primaries...
registry.add_error(/* ... */);

// Generate outputs
registry.generate("./docs", &HtmlRenderer::default())?;
registry.generate("./docs", &JsonRenderer)?;
registry.generate("./docs", &CatalogRenderer::compact())?;

Catalog Formats

use waddling_errors::doc_generator::CatalogRenderer;

CatalogRenderer::new()       // Full - all fields, for development
CatalogRenderer::compact()   // Compact - smaller, for production
CatalogRenderer::minimal()   // Minimal - smallest, hash-to-code only

Custom Renderers

Implement the Renderer trait:

use waddling_errors::doc_generator::{Renderer, DocRegistry, ErrorDoc};

struct XmlRenderer;

impl Renderer for XmlRenderer {
    fn format_name(&self) -> &str { "xml" }

    fn render(
        &self,
        registry: &DocRegistry,
        errors: &[&ErrorDoc],
        output_path: &std::path::Path,
        filter_role: Option<waddling_errors::Role>,
    ) -> std::io::Result<()> {
        // Generate your format
        Ok(())
    }
}

HTML Customization

use waddling_errors::doc_generator::{HtmlRenderer, HtmlCustomization};

let renderer = HtmlRenderer::new()
    .with_customization(
        HtmlCustomization::new()
            .with_logo("https://example.com/logo.png", Some("My Project"))
            .with_accent_color("#3498db")
            .with_footer("© 2024 My Company")
    );

Feature Flags

Default: no_std + alloc. For bare metal: default-features = false.

Documentation

• Feature Flags
• Catalog Guide
• API Reference

License

MIT or Apache-2.0.