diff --git a/src/board/board.rs b/src/board/board.rs index 56d7aa5..dfab4ea 100644 --- a/src/board/board.rs +++ b/src/board/board.rs @@ -20,10 +20,14 @@ use crate::{ math::Circle, }; +/// Represents a band between two pins. #[derive(Debug, Hash, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct BandName(String, String); impl BandName { + /// Creates a new [`BandName`] and manages their order. + /// + /// This function ensures that the two pin names are sorted in lexicographical order, so that the smaller name always comes first. pub fn new(pinname1: String, pinname2: String) -> Self { if pinname1.cmp(&pinname2) == Ordering::Greater { BandName(pinname2, pinname1) @@ -33,6 +37,10 @@ impl BandName { } } +/// Represents a board layout and its associated metadata. +/// +/// The struct manages the relationships between board's layout, +/// and its compounds, as well as provides methods to manipulate them. #[derive(Debug)] pub struct Board { layout: Layout, @@ -41,6 +49,7 @@ pub struct Board { } impl Board { + /// Initializes the board with given [`Layout`] pub fn new(layout: Layout) -> Self { Self { layout, @@ -49,6 +58,9 @@ impl Board { } } + /// Adds a new fixed dot with an optional pin name. + /// + /// Inserts the dot into the layout and, if a pin name is provided, maps it to the created dot's node. pub fn add_fixed_dot_infringably( &mut self, weight: FixedDotWeight, @@ -64,6 +76,9 @@ impl Board { dot } + /// Adds a fixed segment between two dots with an optional pin name. + /// + /// Adds the segment to the layout and maps the pin name to the created segment if provided. pub fn add_poly_fixed_dot_infringably( &mut self, weight: FixedDotWeight, @@ -79,6 +94,9 @@ impl Board { dot } + /// Adds a fixed segment associated with a polygon in the layout. + /// + /// Adds the segment to the layout and updates the internal mapping if necessary. pub fn add_fixed_seg_infringably( &mut self, from: FixedDotIndex, @@ -96,6 +114,9 @@ impl Board { seg } + /// Adds a fixed segment associated with a polygon in the layout. + /// + /// Adds the segment to the layout and updates the internal mapping if necessary. pub fn add_poly_fixed_seg_infringably( &mut self, from: FixedDotIndex, @@ -114,7 +135,10 @@ impl Board { seg } - + + /// Adds a new polygon to the layout with an optional pin name. + /// + /// Inserts the polygon into the layout and, if a pin name is provided, maps it to the created polygon's node. pub fn add_poly( &mut self, weight: PolyWeight, @@ -129,7 +153,10 @@ impl Board { poly } - + + /// Retrieves or creates the apex (top point) of a polygon in the layout. + /// + /// If the polygon already has an apex, returns it. Otherwise, creates and returns a new fixed dot as the apex. pub fn poly_apex(&mut self, poly: GenericIndex) -> FixedDotIndex { if let Some(apex) = self.layout.poly(poly).maybe_apex() { apex @@ -148,18 +175,22 @@ impl Board { } } + /// Returns the pin name associated with a given node. pub fn node_pinname(&self, node: NodeIndex) -> Option<&String> { self.node_to_pinname.get(&node) } + /// Returns the band name associated with a given band. pub fn band_bandname(&self, band: BandUid) -> Option<&BandName> { self.band_bandname.get_by_left(&band) } + /// Returns the unique id associated with a given band name. pub fn bandname_band(&self, bandname: BandName) -> Option<&BandUid> { self.band_bandname.get_by_right(&bandname) } + /// Creates band between the two nodes pub fn try_set_band_between_nodes( &mut self, source: FixedDotIndex, @@ -178,6 +209,7 @@ impl Board { .insert(band, BandName::new(source_pinname, target_pinname)); } + /// Finds a band between two pin names. pub fn band_between_pins(&self, pinname1: &str, pinname2: &str) -> Option { if let Some(band) = self .band_bandname @@ -194,14 +226,17 @@ impl Board { } } + /// Returns the mesadata associated with the layout's drawing rules. pub fn mesadata(&self) -> &M { self.layout.drawing().rules() } + /// Returns the layout managed by this board. pub fn layout(&self) -> &Layout { &self.layout } + /// Returns a mutable reference to the layout, allowing modifications. pub fn layout_mut(&mut self) -> &mut Layout { &mut self.layout } diff --git a/src/board/mesadata.rs b/src/board/mesadata.rs index 2c059ac..64c9fc1 100644 --- a/src/board/mesadata.rs +++ b/src/board/mesadata.rs @@ -1,11 +1,31 @@ +//! Module implementing the logic behind board metadata use crate::drawing::rules::AccessRules; +/// Trait for managing the Specctra's mesadata +/// +/// This trait implements generic function for accessing or modifying different +/// compounds of board parts like nets or layers pub trait AccessMesadata: AccessRules { + /// Renames a layer based on its index. fn bename_layer(&mut self, layer: usize, layername: String); + + /// Retrieves the name of a layer by its index. fn layer_layername(&self, layer: usize) -> Option<&str>; + + /// Retrieves the index of a layer by its name. fn layername_layer(&self, layername: &str) -> Option; + /// Renames a net based on its index. fn bename_net(&mut self, net: usize, netname: String); + + /// Retrieves the name of a net by its index. fn net_netname(&self, net: usize) -> Option<&str>; + + /// Retrieves the index of a net by its name. fn netname_net(&self, netname: &str) -> Option; } + + + + + diff --git a/src/board/mod.rs b/src/board/mod.rs index 34c3a1d..2ced2e4 100644 --- a/src/board/mod.rs +++ b/src/board/mod.rs @@ -1,3 +1,7 @@ +//! Provides the functionality to create and manage relationships +//! between nodes, pins, and bands, as well as handle metadata and geometric data +//! for layout construction. + mod board; pub mod mesadata;