From 22d798a0be38f362be148a5097a569b9f2bd8f08 Mon Sep 17 00:00:00 2001 From: "Simon Keimer (DC0SK)" Date: Wed, 8 Jul 2026 22:13:35 +0200 Subject: [PATCH] feat(lib): intentional, documented public API with a prelude src/lib.rs re-exported whole internal modules with no curated surface or stability contract. Add crate-level API docs (getting-started example that doubles as a doctest), a semver-tracked `prelude` module re-exporting the core stable types (AppConfig, AppResults, run_calculation[_checked], results_display_document, WireCalculation, TransformerRatio, GroundClass, ImpedanceClass, the optimizer config/result types, Band/BandType/ITURegion), and explicit stability notes distinguishing the stable API from advanced-use modules and private implementation details. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/lib.rs | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 7f13487..70f0970 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,8 +1,45 @@ -/// Rusty Wire library entry point. -/// -/// Exposes the I/O-free application layer so that front-ends other than the -/// bundled CLI (e.g. a future `iced` GUI or a test harness) can depend on -/// this crate without pulling in CLI-specific logic. +//! # Rusty Wire +//! +//! Wire-antenna length planning for ham radio, exposed as a library so front-ends +//! other than the bundled CLI (e.g. an `iced` GUI, a bot, or a test harness) can +//! reuse the I/O-free application layer. +//! +//! ## Getting started +//! +//! Build an [`AppConfig`], run it, and read the per-band results: +//! +//! ``` +//! use rusty_wire::prelude::*; +//! +//! let config = AppConfig::default(); +//! let results = run_calculation(config); +//! for calc in &results.calculations { +//! println!("{}: half-wave {:.2} m", calc.band_name, calc.half_wave_m); +//! } +//! +//! // Or render the same document the CLI/TUI print: +//! let doc = results_display_document(&results); +//! assert!(!doc.band_views.is_empty()); +//! ``` +//! +//! Use [`run_calculation_checked`] instead of [`run_calculation`] to validate the +//! configuration first (returns an [`AppError`] on invalid input). +//! +//! ## Public API and stability +//! +//! The **stable, semver-tracked** surface is re-exported from [`prelude`]. Prefer +//! importing from there. +//! +//! The [`app`], [`bands`], [`calculations`], [`prefs`], and [`sessions`] modules +//! are public for advanced use, but items *not* re-exported from [`prelude`] may +//! change in minor releases. The [`tui`] module and the `run_tui` entry point are +//! provided for embedding the terminal UI but are not part of the stable API. The +//! CLI, export, NEC-export, and fnec-validation modules are private implementation +//! details. +//! +//! Semantic-versioning policy: breaking changes to `prelude` items bump the major +//! version; additive changes bump the minor version. + pub mod app; pub(crate) mod band_presets; pub mod bands; @@ -15,6 +52,26 @@ pub mod prefs; pub mod sessions; pub mod tui; +/// The stable, semver-tracked public API. Import everything with +/// `use rusty_wire::prelude::*;`. +/// +/// Anything re-exported here is covered by the crate's semver policy; other +/// public items may change in minor releases. +pub mod prelude { + #[doc(no_inline)] + pub use crate::app::{ + results_display_document, run_calculation, run_calculation_checked, AppConfig, AppError, + AppRequest, AppResponse, AppResults, CalcMode, ResultsDisplayDocument, + }; + #[doc(no_inline)] + pub use crate::bands::{Band, BandType, ITURegion}; + #[doc(no_inline)] + pub use crate::calculations::{ + GroundClass, ImpedanceClass, NonResonantRecommendation, NonResonantSearchConfig, + OcfdSplitRecommendation, ResonantCompromise, TransformerRatio, WireCalculation, + }; +} + /// Run the command-line interface with the given argument list. /// /// Returns `true` on success, `false` if any error prevented completion.