M4 #334: Add # Errors and # Panics doc sections to public fallible functions#370
Merged
Conversation
Added concise # Errors rustdoc sections to all 34 public Result-returning functions across src/model/: - decimal.rs: decimal_to_f64, f64_to_decimal (2) - option.rs: time_to_expiration, calculate_price_binomial_tree, calculate_price_black_scholes, calculate_price_telegraph, payoff, payoff_at_price, intrinsic_value, time_value, calculate_implied_volatility (9) - position.rs: total_cost, premium_received, net_premium_received, pnl_at_expiration, unrealized_pnl, days_held, days_to_expiration, net_cost, fees (9) - trade.rs: TradeStatusAble 6 transitions and 3 Trade accessor methods (9) - leg/traits.rs: delta, gamma, theta, vega, rho (5) - profit_range.rs: ProfitRange::new (1) Each section names the concrete error variant(s) produced or propagated with intra-doc links. Refs #334
Added concise # Errors rustdoc sections to 14 public Result-returning functions across src/chains/: - chain.rs: to_build_params, atm_strike, save_to_csv, save_to_csv_async, save_to_json, save_to_json_async, load_from_csv, load_from_csv_async, load_from_json, load_from_json_async, get_random_positions, set_optiondata_extra_params (12) - rnd.rs: RNDAnalysis::calculate_rnd, calculate_skew (2) Each section references concrete ChainError variants with intra-doc links and mentions the spawn_blocking join-failure path for async wrappers. Refs #334
Added concise # Errors rustdoc sections to 46 public Result-returning functions and trait methods across src/strategies/: - base.rs: 18 Strategable / BreakEvenable / PositionAble trait methods - build/traits.rs: get_strategy (1) - collar.rs: net_delta, max_profit_potential, max_loss_potential (3) - covered_call.rs: net_delta, max_profit_potential, max_loss_potential (3) - protective_put.rs: net_delta, max_loss_potential (2) - delta_neutral/model.rs: 9 DeltaNeutrality trait methods - delta_neutral/optimizer.rs: optimize (1) - delta_neutral/portfolio.rs: from_positions, from_positions_with_underlying (2) - probabilities/core.rs: 7 ProbabilityAnalysis trait methods - shared.rs: calculate_profit_ratio (1) Each section references concrete error variants with intra-doc links and calls out propagated errors versus variants produced locally. Refs #334
Added concise # Errors rustdoc sections to 16 public Result-returning functions across src/greeks/: - equations.rs: gamma, theta, vega, rho, rho_d, vanna, vomma, veta, charm, color (10 analytical Greeks) - numerical.rs: numerical_delta, numerical_gamma, numerical_vega, numerical_theta, numerical_rho (5) - utils.rs: calculate_delta_neutral_sizes (1) Each section references concrete error variants (GreeksError::Pricing, ExpirationDate, DeltaNeutrality with kind) via intra-doc links. Refs #334
Added concise # Errors rustdoc sections to 11 public Result-returning functions across src/volatility/: - traits.rs: AtmIvProvider::atm_iv (1) - utils.rs: constant_volatility, historical_volatility, ewma_volatility, implied_volatility, garch_volatility, simulate_heston_volatility, uncertain_volatility_bounds, annualized_volatility, de_annualized_volatility, adjust_volatility (10) Each section references concrete VolatilityError variants (AtmIvUnavailable, IvNotFound, NoConvergence, NumericalFailure, PositiveError, InvalidTime, Options) via intra-doc links. Refs #334
Added concise # Errors rustdoc sections to 28 public Result-returning
functions across src/pricing/ and src/metrics/:
- pricing/american.rs: barone_adesi_whaley (1)
- pricing/binomial_model.rs: price_binomial, generate_binomial_tree (2)
- pricing/barrier.rs, binary.rs, lookback.rs, compound.rs, chooser.rs,
cliquet.rs: *_black_scholes for each exotic (6)
- pricing/black_scholes_model.rs: black_scholes, BlackScholes trait
get_option + calculate_price_black_scholes (3)
- pricing/monte_carlo.rs: monte_carlo_option_pricing (1)
- pricing/payoff.rs: Profit::calculate_profit_at, get_point_at_price (2)
- pricing/telegraph.rs: telegraph (1)
- pricing/utils.rs: simulate_returns (1)
- pricing/unified.rs: price_option, Priceable::price (2)
- metrics/price/{put_call_ratio,strike_concentration,volatility_skew}.rs:
one trait method each (3)
- metrics/stress/{price_shock,time_decay,volatility_sensitivity}.rs:
one *_surface trait method each (3)
- metrics/temporal/{charm,color,theta}.rs: one *_surface trait method
each (3)
Each section references concrete error variants (PricingError,
SurfaceError, CurveError, DecimalError) via intra-doc links.
Refs #334
Added concise # Errors rustdoc sections to 67 public Result-returning
functions across src/simulation/, src/geometrics/, src/curves/,
src/surfaces/, src/pnl/, src/visualization/, src/utils/:
- simulation/params.rs: ystep_as_positive (1)
- simulation/steps/step.rs: next, previous, get_graph_x_value,
get_graph_y_value, get_positive_value (5)
- simulation/steps/x.rs: days_left, next, previous (3)
- simulation/steps/y.rs: positive (1)
- simulation/traits.rs: brownian, geometric_brownian, log_returns,
mean_reverting, jump_diffusion, garch, heston, custom,
telegraph (9)
- geometrics/analysis/metrics.rs: analysis_result (1)
- geometrics/analysis/traits.rs: compute_basic/shape/range/trend/risk
/curve_metrics (6)
- geometrics/interpolation/{linear,cubic,bilinear,spline}.rs and
traits.rs: 5 algorithm methods (5)
- geometrics/operations/axis.rs: get_closest_point,
merge_axis_interpolate (2)
- geometrics/operations/traits.rs: merge, merge_with (2)
- geometrics/operations/transformations.rs: translate, scale,
intersect_with, derivative_at, extrema, measure_under (6)
- geometrics/utils.rs: construct (1)
- curves/basic.rs: curve, get_curve_strike_versus (2)
- curves/traits.rs: generate_statistical_curve,
generate_refined_statistical_curve, verify_curve_metrics (3)
- curves/types.rs: Point2D::from_tuple (1)
- surfaces/basic.rs: surface, time_surface (2)
- surfaces/traits.rs: Surfacable::surface (1)
- surfaces/types.rs: Point3D::{to_tuple, from_tuple, to_f64_tuple,
from_f64_tuple} (4)
- pnl/metrics.rs: save_pnl_metrics, load_pnl_metrics (2)
- pnl/traits.rs: calculate_pnl, calculate_pnl_at_expiration,
TransactionAble::{add_transaction, get_transactions} (4)
- pnl/transaction.rs: Transaction::pnl (1)
- utils/csv.rs: read_ohlcv_from_zip_async (1)
- utils/file.rs: prepare_file_path (1)
- visualization/plotly.rs: show, render, to_interactive_html (3)
Each section references concrete error variants via intra-doc links.
Phase A complete: cargo clippy --lib -- -W missing_errors_doc now
reports 0 warnings.
Refs #334
Completes Phase B of the panic audit:
- cargo clippy --lib -- -W missing_panics_doc reports 0 warnings.
- Manual sweep of production unwrap/expect/panic! sites confirms
every remaining panic is intentional and inline-documented:
* src/constants.rs (7): unwrap_or_else(|e| unreachable!(...)) on
compile-time literals that are provably valid.
* src/strategies/base.rs (2): one_option / one_option_mut trait
defaults already carry # Panics documentation.
* src/surfaces/surface.rs and src/curves/curve.rs (1 each):
std::ops::Index impls already carry # Panics documentation
matching the trait's own contract.
* src/model/decimal.rs decimal_normal_sample: now documented.
The selected "Full sweep + fix" option was scoped down to
documenting the one remaining undocumented panic rather than
refactoring the Index impls or the base.rs trait defaults \u2014 both
cases are legitimate uses of panic where no Result return is
expressible, and the inline invariant messages make the contract
explicit.
Refs #334
Strip intra-doc link brackets on 60 symbols that rustdoc could not resolve (nested variants, private items, ambiguous names). Each becomes a plain backtick code span, preserving the # Errors / # Panics text without generating doc-build warnings. - MAX_ITERATIONS_IV (private), Sx (literal), OptionsError, PricingError::*, PositionError::*, FileErrorKind::*, StrategyErrorKind::*, ProbabilityCalculationErrorKind::*, CurveError::GreeksError, GraphError::*, AdjustmentError::*, Strategable::*, compute_*_metrics, numerical_*, price_binomial, delta_*, etc. - Disambiguate [`telegraph`] to the kernel name in prose form (module vs function collision). RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features now builds clean. Refs #334
joaquinbejar
added
documentation
Codecov Report✅ All modified and coverable lines are covered by tests.
🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR is a documentation sweep across OptionStratLib to satisfy clippy’s missing_errors_doc / missing_panics_doc lints by adding concise rustdoc # Errors sections to public fallible APIs, completing a remaining panic audit item, and removing/adjusting broken intra-doc links so cargo doc builds with -D warnings.
Changes:
- Add
# Errorssections to publicResult-returning functions/traits across the library. - Add a
# Panicssection fordecimal_normal_sample’sunreachable!path. - Strip/adjust broken intra-doc links to avoid rustdoc warning errors.
Reviewed changes
Copilot reviewed 75 out of 75 changed files in this pull request and generated 22 comments.
Show a summary per file
| File | Description |
|---|---|
| src/volatility/utils.rs | Adds # Errors docs to volatility utilities. |
| src/volatility/traits.rs | Adds # Errors docs to volatility traits. |
| src/visualization/plotly.rs | Adds # Errors docs to graph rendering/show helpers. |
| src/utils/file.rs | Documents I/O error surface for file-path preparation. |
| src/utils/csv.rs | Documents async ZIP/CSV read error surface. |
| src/surfaces/types.rs | Documents Point3D tuple conversions error surface. |
| src/surfaces/traits.rs | Documents surface construction error surface for trait. |
| src/surfaces/basic.rs | Documents construction/runtime surface sampling errors. |
| src/strategies/shared.rs | Documents (in)fallibility of shared strategy helpers. |
| src/strategies/protective_put.rs | Documents errors for strategy greek/pricing helpers. |
| src/strategies/probabilities/core.rs | Documents probability analysis error propagation. |
| src/strategies/delta_neutral/portfolio.rs | Documents portfolio greeks aggregation errors. |
| src/strategies/delta_neutral/optimizer.rs | Documents optimizer failure modes. |
| src/strategies/delta_neutral/model.rs | Documents delta-neutrality workflow error propagation. |
| src/strategies/covered_call.rs | Documents errors for covered-call metrics. |
| src/strategies/collar.rs | Documents errors for collar metrics. |
| src/strategies/build/traits.rs | Documents constructor validation errors. |
| src/strategies/base.rs | Documents default-trait error behavior and propagation. |
| src/simulation/traits.rs | Documents walk generator error surfaces. |
| src/simulation/steps/y.rs | Documents step-to-Positive conversion errors. |
| src/simulation/steps/x.rs | Documents X-step time/iteration errors. |
| src/simulation/steps/step.rs | Documents step traversal/conversion errors. |
| src/simulation/params.rs | Documents parameter-to-positive conversion errors. |
| src/pricing/utils.rs | Documents decimal simulation utility error surface. |
| src/pricing/unified.rs | Documents unified pricing engine error propagation. |
| src/pricing/telegraph.rs | Documents telegraph pricer error surface. |
| src/pricing/payoff.rs | Documents payoff/profit trait error surface. |
| src/pricing/monte_carlo.rs | Documents Monte Carlo pricer error surface. |
| src/pricing/lookback.rs | Documents lookback pricer error surface. |
| src/pricing/compound.rs | Documents compound pricer error surface. |
| src/pricing/cliquet.rs | Documents cliquet pricer error surface. |
| src/pricing/chooser.rs | Documents chooser pricer error surface. |
| src/pricing/black_scholes_model.rs | Documents Black–Scholes pricer and trait errors. |
| src/pricing/binomial_model.rs | Documents binomial pricer/tree errors. |
| src/pricing/binary.rs | Documents binary pricer error surface. |
| src/pricing/barrier.rs | Documents barrier pricer error surface. |
| src/pricing/american.rs | Documents Barone–Adesi–Whaley error surface. |
| src/pnl/transaction.rs | Documents transaction PnL computation errors. |
| src/pnl/traits.rs | Documents PnL and transaction-log trait errors. |
| src/pnl/metrics.rs | Documents JSON save/load I/O + serde error surfaces. |
| src/model/trade.rs | Documents trade status transitions and accessors errors. |
| src/model/profit_range.rs | Documents profit-range constructor errors. |
| src/model/position.rs | Documents position cost/premium/PnL helper errors. |
| src/model/option.rs | Documents option pricing/payoff/time/IV errors. |
| src/model/leg/traits.rs | Documents greek trait method error surfaces. |
| src/model/decimal.rs | Adds # Panics docs for decimal_normal_sample. |
| src/metrics/temporal/theta.rs | Documents theta surface construction errors. |
| src/metrics/temporal/color.rs | Documents color surface construction errors. |
| src/metrics/temporal/charm.rs | Documents charm surface construction errors. |
| src/metrics/stress/volatility_sensitivity.rs | Documents vol-sensitivity surface errors. |
| src/metrics/stress/time_decay.rs | Documents time-decay surface errors. |
| src/metrics/stress/price_shock.rs | Documents price-shock surface errors. |
| src/metrics/price/volatility_skew.rs | Documents skew curve construction/interp errors. |
| src/metrics/price/strike_concentration.rs | Documents concentration curve error surface. |
| src/metrics/price/put_call_ratio.rs | Documents PCR curve error surface. |
| src/greeks/utils.rs | Documents delta-neutral sizing helper errors. |
| src/greeks/numerical.rs | Documents numerical greeks error propagation. |
| src/greeks/equations.rs | Documents analytical/numerical greek errors. |
| src/geometrics/utils.rs | Documents generic geometry construction errors. |
| src/geometrics/operations/transformations.rs | Documents transformation operation errors. |
| src/geometrics/operations/traits.rs | Documents merge/merge_with error surface. |
| src/geometrics/operations/axis.rs | Documents axis ops error surface. |
| src/geometrics/interpolation/traits.rs | Documents interpolation dispatcher errors. |
| src/geometrics/interpolation/spline.rs | Documents spline interpolation errors. |
| src/geometrics/interpolation/linear.rs | Documents linear interpolation errors. |
| src/geometrics/interpolation/cubic.rs | Documents cubic interpolation errors. |
| src/geometrics/interpolation/bilinear.rs | Documents bilinear interpolation errors. |
| src/geometrics/analysis/traits.rs | Documents metrics extraction errors. |
| src/geometrics/analysis/metrics.rs | Documents metrics-to-analysis result errors. |
| src/error/options.rs | Adjusts docs to avoid broken intra-doc link warnings. |
| src/curves/types.rs | Documents Point2D tuple-construction errors semantics. |
| src/curves/traits.rs | Documents statistical-curve errors. |
| src/curves/basic.rs | Documents curve construction error surface. |
| src/chains/rnd.rs | Documents RND analysis error surface. |
| src/chains/chain.rs | Documents chain utility error surfaces. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+30
to
+35
| /// # Errors | ||
| /// | ||
| /// Returns [`VolatilityError::NumericalFailure`] when the length of | ||
| /// `returns` cannot be represented as a `Decimal` or when the | ||
| /// variance computation overflows, and [`VolatilityError::PositiveError`] | ||
| /// if the final square-root produces a non-positive candidate. |
Owner
Author
There was a problem hiding this comment.
Updated, the doc now says constant_volatility is infallible on the Positive conversion (clamped) and only returns NumericalFailure when len-as-Decimal or sqrt(variance) fail.
Comment on lines
+156
to
+163
| /// # Errors | ||
| /// | ||
| /// Returns [`VolatilityError::NoConvergence`] when the Newton–Raphson | ||
| /// iteration exhausts `MAX_ITERATIONS_IV` without matching the target | ||
| /// price, [`VolatilityError::IvNotFound`] when the search grid never | ||
| /// produced a valid candidate, or propagates | ||
| /// [`VolatilityError::Options`] from the underlying Black–Scholes | ||
| /// evaluation on each iteration. |
Owner
Author
There was a problem hiding this comment.
Rewrote the section, it now says implied_volatility is a parallel grid search, returns IvNotFound when the best candidate is the lower boundary, NoValidVolatility when every grid point fails BS, and PositiveError from the boundary conversion. BS errors are discarded, not propagated.
Comment on lines
+235
to
+239
| /// The `unreachable!` branch fires only if | ||
| /// `statrs::distribution::Normal::new(0.0, 1.0)` rejects the standard | ||
| /// normal parameters — a provably impossible state the standard | ||
| /// library upholds at all supported versions. Kept as a panic | ||
| /// rather than `Result` to preserve the infallible sampling API. |
Owner
Author
There was a problem hiding this comment.
Good catch, reworded to point at the statrs::distribution::Normal::new contract (finite mean, strictly positive std_dev) instead of the std library.
Comment on lines
+405
to
+415
| /// Calculates the maximum loss potential. | ||
| /// | ||
| /// Max Loss = (Cost Basis - Put Strike) × Quantity - Net Premium + Fees | ||
| /// | ||
| /// # Errors | ||
| /// | ||
| /// Returns `PricingError::MethodError` with method `collar` when | ||
| /// the loss decomposition underflows (for example when the put strike | ||
| /// equals or exceeds the spot cost basis and the net premium net of | ||
| /// fees is positive), or when arithmetic fails while converting | ||
| /// `Positive` operands. |
Owner
Author
There was a problem hiding this comment.
Documented max_loss_potential as currently infallible with Positive::new_decimal(total_loss.max(Decimal::ZERO)).unwrap_or(Positive::ZERO), keeping the Result for forward compatibility.
Comment on lines
+244
to
+249
| /// # Errors | ||
| /// | ||
| /// Returns [`SimulationError::ExpirationDate`] when the | ||
| /// underlying [`ExpirationDate::get_days`] call fails, or | ||
| /// [`SimulationError::IndexConversion`] when the step index | ||
| /// decrement would underflow `i32::MIN`. |
Owner
Author
There was a problem hiding this comment.
Moved the underflow note to a # Panics section and kept # Errors for the ExpirationDate/step_size_error paths. The unchecked decrement is a caller invariant rather than a runtime check.
Comment on lines
+375
to
+385
| /// Calculates the maximum profit potential. | ||
| /// | ||
| /// Max Profit = (Call Strike - Cost Basis) × Quantity + Net Premium - Fees | ||
| /// | ||
| /// # Errors | ||
| /// | ||
| /// Returns `PricingError::MethodError` with method `collar` when | ||
| /// the short-call strike is below the spot cost basis (the strategy | ||
| /// is not economically well-formed). Arithmetic follows | ||
| /// `PricingError::ArithmeticFailure` if fee or premium conversions | ||
| /// overflow. |
Owner
Author
There was a problem hiding this comment.
Documented max_profit_potential as infallible, both branches clamp via Positive::new_decimal(total_profit.max(Decimal::ZERO)).unwrap_or(Positive::ZERO).
Comment on lines
+303
to
+308
| /// # Errors | ||
| /// | ||
| /// Returns [`PositionError::invalid_position_type`] for a long position | ||
| /// (which never receives a premium), or wraps a `Positive`-conversion | ||
| /// failure when `premium × quantity` cannot be represented as a | ||
| /// non-negative decimal. |
Owner
Author
There was a problem hiding this comment.
Updated premium_received to describe the actual two-branch Ok: Long returns Positive::ZERO and Short returns premium * quantity, no Err is produced.
Comment on lines
+100
to
+105
| /// # Errors | ||
| /// | ||
| /// Returns [`VolatilityError::NumericalFailure`] when the EWMA | ||
| /// recurrence overflows or produces a negative running variance, and | ||
| /// [`VolatilityError::PositiveError`] when a running square-root | ||
| /// violates the `Positive` invariant. |
Owner
Author
There was a problem hiding this comment.
Rewrote ewma_volatility's section: NumericalFailure fires on empty input and on failed sqrt(variance); the Positive::new_decimal(...) conversion is clamped so PositiveError is not surfaced.
Comment on lines
+245
to
+250
| /// # Errors | ||
| /// | ||
| /// Returns [`PositionError`] wrapping a [`PositionValidationErrorKind::InvalidPosition`] | ||
| /// when the total cost computation underflows into a negative | ||
| /// `Positive`-representable value (typically a short position where the | ||
| /// received premium exceeds the declared costs). |
Owner
Author
There was a problem hiding this comment.
Documented total_cost as currently infallible: long sums non-negative Positive terms and short delegates to fees() which is itself infallible under the current impl.
Comment on lines
+47
to
+52
| /// # Errors | ||
| /// | ||
| /// Returns [`ProbabilityError`] wrapping a | ||
| /// `ProbabilityCalculationErrorKind::InvalidProbability` when `lower_bound` | ||
| /// is greater than `upper_bound`, or `ProbabilityCalculationErrorKind::InvalidProbabilityRange` | ||
| /// when the `probability` value lies outside the closed interval `[0, 1]`. |
Owner
Author
There was a problem hiding this comment.
Fixed, the doc now points to ProbabilityError::RangeError wrapping ProfitLossRangeErrorKind::InvalidProfitRange and notes that probability is not currently validated against [0, 1].
Copilot review on PR #370 flagged 22 inline comments where the new # Errors sections described error variants that the implementations never actually return (each function clamps intermediate values with unwrap_or(Positive::ZERO) or max(Decimal::ZERO) rather than surfacing an Err). This commit rewrites the affected sections to truthfully describe the current (mostly infallible / clamping) behaviour and preserves the Result signature for forward compatibility. - volatility/utils.rs: drop never-returned PositiveError mentions on constant_volatility, ewma_volatility, simulate_heston_volatility; rewrite implied_volatility docs to match the parallel grid search (not Newton-Raphson); document garch_volatility as currently infallible with a # Panics note for empty input; document historical_volatility as propagating only NumericalFailure with a # Panics note for window_size == 0. - model/position.rs: document total_cost, premium_received and net_premium_received as currently infallible / clamping instead of returning PositionError. - strategies/{collar, covered_call, protective_put}.rs: document max_profit_potential and max_loss_potential as currently infallible clamping functions rather than claiming unreturned PricingError::MethodError variants. - simulation/steps/x.rs: acknowledge that Xstep::previous does an unchecked index decrement (# Panics) rather than returning IndexConversion. - simulation/traits.rs: clarify that brownian's only PositiveError source is the ystep conversion; generated samples are clamped. - surfaces/types.rs: document the positivity checks on Point3D::to_tuple. - visualization/plotly.rs: fix GraphError variant names (Render / Io). - volatility/traits.rs: realign atm_iv Returns and Errors with the actual Result<&Positive, VolatilityError> signature. - error/options.rs: drop the literal HTML-fragment hint. - model/decimal.rs: clarify that decimal_normal_sample's unreachable branch is guaranteed by the statrs contract, not std. - model/profit_range.rs: document the real RangeError variant and note that probability is not currently validated. No production logic changed. cargo clippy --lib -- -W missing_errors_doc -W missing_panics_doc still reports 0 warnings and the strict-warnings doc build stays clean. Refs #334
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds concise
# Errorsrustdoc sections to every publicResult-returning function in the OptionStratLib library and completes the# Panicsaudit so thatcargo clippy -- -W missing_errors_doc -W missing_panics_docreports 0 warnings.Changes
# Errorssections added across 74 library files coveringmodel/,chains/,strategies/,greeks/,volatility/,pricing/,metrics/,simulation/,geometrics/,curves/,surfaces/,pnl/,visualization/andutils/.# Panicssection added ondecimal_normal_sampleto explain the provably-unreachablestatrs::Normal::new(0.0, 1.0)error path.RUSTDOCFLAGS="-D warnings" cargo doc --no-depsnow builds clean (targets that live in nested sub-enums or private modules do not resolve from the calling function's scope).Technical Decisions
cargo clippy -- -W missing_panics_docalready reported 0 warnings before this PR. A manual sweep confirmed the remaining 12 productionunwrap!/expect!/panic!/unreachable!sites are all intentional and documented:src/constants.rsguard compile-time literal construction (pub constinitialisers) with explanatoryunreachable!messages.src/strategies/base.rs(one_option/one_option_muttrait defaults) already carry# Panicssections because the&Options/&mut Optionsreturn types admit no safe fallback.std::ops::Indeximpls forSurfaceandCurvealready carry# Panicssections matching theVec<T>::indexcontract.decimal_normal_samplefixed by this PR.Indeximpls or trait defaults — both are legitimate uses of panic where noResultreturn is expressible, and the inline invariant messages make the contract explicit. No production code paths were changed in this PR.FileErrorKind::IOError, private items likeMAX_ITERATIONS_IV, or ambiguous names liketelegraph), the reference is rendered as a plain backtick code span instead of[\Foo::Bar`]`. Search-in-source still finds the symbol; this keeps the doc build strict-warning clean.Testing
cargo test --all-features)Test counts (all passing):
Checklist
.windsurfrules///documentation (219 new sections added)cargo clippy --lib -- -W missing_errors_doc -W missing_panics_doc= 0 warningscargo clippy --all-targets --all-features --workspace -- -D warningscleanRUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-featurescleancargo fmt --all --checkpasses.unwrap(),.expect(), or panics in library codemake pre-pushclean (only a pre-existingmissing-docswarning onutils/time::units_per_year, unrelated to this PR)Closes #334