specctra: added very initial version of the docs

src/specctra/design.rs

@@ -31,12 +31,30 @@ pub enum LoadingError {
     Parse(#[from] read::ParseError),
 }
 
+
+/// This struct is responsible for managing the various Specctra components of a PCB design,
+/// including parsing the DSN file, handling the resolution and unit of measurement,
+/// and organizing the PCB's structure, placement, library, network, and wiring.
+/// It provides functionality for reading from a DSN file and writing session files.
 #[derive(Debug)]
 pub struct SpecctraDesign {
     pcb: Pcb,
 }
 
 impl SpecctraDesign {
+    /// Reads a Specctra DSN file and initializes a `SpecctraDesign` instance.
+    /// 
+    /// # Errors
+    ///
+    /// Returns a `LoadingError` if an I/O error occurs or if the file format is invalid.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let design_file = File::open("random_design.dsn").unwrap();
+    /// let design_bufread = BufReader::new(design_file);
+    /// let design = SpecctraDesign::load(design_bufread).unwrap();
+    /// ```
     pub fn load(reader: impl std::io::BufRead) -> Result<SpecctraDesign, LoadingError> {
         let mut list_reader = ListTokenizer::new(reader);
         let dsn = list_reader.read_value::<DsnFile>()?;
@@ -44,10 +62,31 @@ impl SpecctraDesign {
         Ok(Self { pcb: dsn.pcb })
     }
 
+    /// Retrieves the name of the PCB design and return name of the PCB as a string slice. 
+    /// 
+    /// # Examples
+    /// 
+    /// FIXME add more detailed info
+    /// ```
+    /// let name = design.get_name();
+    /// ```
     pub fn get_name(&self) -> &str {
         &self.pcb.name
     }
     
+    /// This method generates an SES file based on the board layout and writes it to the specified writer.
+    /// 
+    /// # Errors
+    ///
+    /// Returns an `std::io::Error` if an I/O error occurs while writing the SES file.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let board = invoker.autorouter().board();
+    /// let mut writebuf = vec![];
+    /// design.write_ses(board, &mut writebuf);
+    /// ```
     pub fn write_ses(
         &self,
         board: &Board<SpecctraMesadata>,
@@ -153,6 +192,18 @@ impl SpecctraDesign {
         ListWriter::new(writer).write_value(&ses)
     }
 
+    
+    /// This method interprets the PCB design and generates a `Board<SpecctraMesadata>` object
+    /// containing the layout and associated Specctra mesadata .
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let design_file = File::open("random_file.dsn")?;
+    /// let mut design_bufread = BufReader::new(design_file);
+    /// let design = SpecctraDesign::load(design_bufread).unwrap();
+    /// let board = design.make_board();
+    /// ```
     pub fn make_board(&self) -> Board<SpecctraMesadata> {
         let mesadata = SpecctraMesadata::from_pcb(&self.pcb);
         let mut board = Board::new(Layout::new(Drawing::new(