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 <hakki@noreply.codeberg.org>
Co-committed-by: hakki <hakki@noreply.codeberg.org>

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<dyn Iterator<Item = EdgeIndex<usize>>>,
+    /// 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<RouteStepper>,
+    /// Keeps track of the current ratline being routed, if one is active.
     curr_ratline: Option<EdgeIndex<usize>>,
 }
 
 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<impl AccessMesadata>,
         ratlines: impl IntoIterator<Item = EdgeIndex<usize>> + 'static,
@@ -120,24 +143,28 @@ impl<M: AccessMesadata> Step<Autorouter<M>, 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())
     }

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::{

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;
 

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;

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,

src/autorouter/mod.rs

@@ -1,3 +1,5 @@
+//! Manages autorouting process, under work for now
+
 pub mod autoroute;
 mod autorouter;
 pub mod command;

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,

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;

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,