From 2f672d41c223a204fcb1859694f7f477a6dfde4f Mon Sep 17 00:00:00 2001 From: hakki Date: Wed, 2 Oct 2024 22:46:32 +0000 Subject: [PATCH] Autorouter: general modules descriptions (#65) This PR consists of general modules descriptions as well as initial `autoroute.rs` docs Reviewed-on: https://codeberg.org/topola/topola/pulls/65 Co-authored-by: hakki Co-committed-by: hakki --- src/autorouter/autoroute.rs | 27 +++++++++++++++++++++++++++ src/autorouter/compare_detours.rs | 5 +++++ src/autorouter/history.rs | 4 ++++ src/autorouter/invoker.rs | 2 ++ src/autorouter/measure_length.rs | 4 ++++ src/autorouter/mod.rs | 2 ++ src/autorouter/place_via.rs | 4 ++++ src/autorouter/ratsnest.rs | 5 +++++ src/autorouter/remove_bands.rs | 5 +++++ 9 files changed, 58 insertions(+) diff --git a/src/autorouter/autoroute.rs b/src/autorouter/autoroute.rs index 0884881..a2e30f5 100644 --- a/src/autorouter/autoroute.rs +++ b/src/autorouter/autoroute.rs @@ -1,3 +1,7 @@ +//! Manages autorouting of ratlines in a layout, tracking status and processed +//! routing steps. Provides access to navigation meshes, traces, ghost shapes, +//! and obstacles encountered during routing. + use petgraph::graph::EdgeIndex; use crate::{ @@ -13,14 +17,23 @@ use super::{ Autorouter, AutorouterError, AutorouterOptions, }; +/// Represents the current status of the autoroute operation. pub enum AutorouteStatus { + /// The autoroute is currently running and in progress. Running, + /// A specific segment has been successfully routed. Routed(BandTermsegIndex), + /// The autoroute process has completed successfully. Finished, } impl TryInto<()> for AutorouteStatus { type Error = (); + /// Attempts to get the [`Result`] from the [`AutorouteStatus`]. + /// + /// This implementation allows transitioning from [`AutorouteStatus`] to a + /// [`Result`]. It returns success for the [`AutorouteStatus::Finished`] state + /// or an error for [`AutorouteStatus::Running`] or [`AutorouteStatus::Routed`] states. fn try_into(self) -> Result<(), ()> { match self { AutorouteStatus::Running => Err(()), @@ -30,14 +43,24 @@ impl TryInto<()> for AutorouteStatus { } } +/// Manages the autorouting process across multiple ratlines. pub struct AutorouteExecutionStepper { + /// An iterator over ratlines that tracks which segments still need to be routed. ratlines_iter: Box>>, + /// The options for the autorouting process, defining how routing should be carried out. options: AutorouterOptions, + /// Stores the current route being processed, if any. route: Option, + /// Keeps track of the current ratline being routed, if one is active. curr_ratline: Option>, } impl AutorouteExecutionStepper { + /// Initializes a new [`AutorouteExecutionStepper`] instance. + /// + /// This method sets up the routing process by accepting the execution properties. + /// It prepares the first ratline to route + /// and stores the associated data for future routing steps. pub fn new( autorouter: &mut Autorouter, ratlines: impl IntoIterator> + 'static, @@ -120,24 +143,28 @@ impl Step, AutorouteStatus, AutorouterError, () } impl GetMaybeNavmesh for AutorouteExecutionStepper { + /// Retrieves an optional reference to the navigation mesh from the current route. fn maybe_navmesh(&self) -> Option<&Navmesh> { self.route.as_ref().map(|route| route.navmesh()) } } impl GetMaybeTrace for AutorouteExecutionStepper { + /// Retrieves an optional reference to the trace from the current route. fn maybe_trace(&self) -> Option<&TraceStepper> { self.route.as_ref().map(|route| route.trace()) } } impl GetGhosts for AutorouteExecutionStepper { + /// Retrieves ghost shapes from the current route. fn ghosts(&self) -> &[PrimitiveShape] { self.route.as_ref().map_or(&[], |route| route.ghosts()) } } impl GetObstacles for AutorouteExecutionStepper { + /// Retrieves obstacles encountered during routing. fn obstacles(&self) -> &[PrimitiveIndex] { self.route.as_ref().map_or(&[], |route| route.obstacles()) } diff --git a/src/autorouter/compare_detours.rs b/src/autorouter/compare_detours.rs index e06dbc6..122332c 100644 --- a/src/autorouter/compare_detours.rs +++ b/src/autorouter/compare_detours.rs @@ -1,3 +1,8 @@ +//! Manages the comparison of detours between two ratlines, tracking their +//! routing statuses and lengths. Facilitates stepwise processing of routing +//! while providing access to navigation meshes, traces, ghost shapes, and +//! obstacles encountered. + use petgraph::graph::EdgeIndex; use crate::{ diff --git a/src/autorouter/history.rs b/src/autorouter/history.rs index 18ea10f..4db7814 100644 --- a/src/autorouter/history.rs +++ b/src/autorouter/history.rs @@ -1,3 +1,7 @@ +//! Manages command history operations, allowing for undoing and redoing commands. +//! Handles error scenarios related to command history, maintaining lists of executed +//! and undone commands for easy navigation. + use serde::{Deserialize, Serialize}; use thiserror::Error; diff --git a/src/autorouter/invoker.rs b/src/autorouter/invoker.rs index 53f1043..3fb76e2 100644 --- a/src/autorouter/invoker.rs +++ b/src/autorouter/invoker.rs @@ -1,3 +1,5 @@ +//! Manages the execution of routing commands within the autorouting system. + use std::cmp::Ordering; use contracts::debug_requires; diff --git a/src/autorouter/measure_length.rs b/src/autorouter/measure_length.rs index f38c2ac..c20e70a 100644 --- a/src/autorouter/measure_length.rs +++ b/src/autorouter/measure_length.rs @@ -1,3 +1,7 @@ +//! Provides functionality for measuring the total length of selected +//! bands in a PCB layout. It interacts with the autorouter to calculate and return +//! the length of specified band selections. + use crate::{ board::mesadata::AccessMesadata, drawing::graph::PrimitiveIndex, diff --git a/src/autorouter/mod.rs b/src/autorouter/mod.rs index 1c638b3..c161fe0 100644 --- a/src/autorouter/mod.rs +++ b/src/autorouter/mod.rs @@ -1,3 +1,5 @@ +//! Manages autorouting process, under work for now + pub mod autoroute; mod autorouter; pub mod command; diff --git a/src/autorouter/place_via.rs b/src/autorouter/place_via.rs index b81a92d..e6de21a 100644 --- a/src/autorouter/place_via.rs +++ b/src/autorouter/place_via.rs @@ -1,3 +1,7 @@ +//! Provides functionality for placing vias in a PCB layout, manages +//! the process of inserting a via with a specified weight and +//! checks if the via has already been placed. + use crate::{ board::mesadata::AccessMesadata, drawing::graph::PrimitiveIndex, diff --git a/src/autorouter/ratsnest.rs b/src/autorouter/ratsnest.rs index 61cc7dd..80dd9a9 100644 --- a/src/autorouter/ratsnest.rs +++ b/src/autorouter/ratsnest.rs @@ -1,3 +1,8 @@ +//! Defines data structures and methods for managing a graph +//! used in layout triangulation and routing tasks. It includes vertex and edge +//! structures for representing graph nodes and edges with associated metadata, +//! as well as functions for constructing and manipulating these graphs. + use std::collections::HashMap; use enum_dispatch::enum_dispatch; diff --git a/src/autorouter/remove_bands.rs b/src/autorouter/remove_bands.rs index 3524c53..272ca66 100644 --- a/src/autorouter/remove_bands.rs +++ b/src/autorouter/remove_bands.rs @@ -1,3 +1,8 @@ +//! Provides functionality to remove bands from the layout in an +//! autorouting context. It defines a struct that interacts with the autorouter +//! to remove selected bands, and implements necessary traits for working +//! with navigation meshes, traces, and obstacles. + use crate::{ board::mesadata::AccessMesadata, drawing::graph::PrimitiveIndex,