Add documentation

README.md

@@ -2,7 +2,7 @@
 
 [Changelog](https://github.com/VincentFoulon80/virt-ic/releases)
 
-This library is a Integrated Circuit Emulator backend that can simulate interractions between multiple chips.
+This library is a Integrated Circuit Emulator backend that can simulate interactions between multiple chips.
 
 You start by creating a Board, and then you add Traces or Sockets, and then you plug Chips and link Pins together to form a virtual circuit.
 You can then run the circuit to emulate the chips and links between them.

src/board.rs

@@ -2,6 +2,7 @@ use super::{Trace, Socket, Chip};
 use std::cell::RefCell;
 use std::rc::Rc;
 
+/// A Board that contains Traces and Sockets
 #[derive(Default)]
 pub struct Board {
     traces: Vec<Rc<RefCell<Trace>>>,
@@ -21,13 +22,16 @@ impl Board {
     pub fn new_trace(&mut self) -> Rc<RefCell<Trace>> {
         let trace = Rc::new(RefCell::new(Trace::new()));
         self.traces.push(trace);
+        // unwrap because we just pushed a value so there's no reason to get a None here
         self.traces.last_mut().unwrap().clone()
     }
 
     /// Create a new socket and return it
+    /// Note that you'll have to plug a chip on it before linking it with the traces
     pub fn new_socket(&mut self) -> Rc<RefCell<Socket>> {
         let socket = Rc::new(RefCell::new(Socket::new()));
         self.sockets.push(socket);
+        // unwrap because we just pushed a value so there's no reason to get a None here
         self.sockets.last_mut().unwrap().clone()
     }
 
@@ -36,10 +40,12 @@ impl Board {
         let socket = Rc::new(RefCell::new(Socket::new()));
         socket.borrow_mut().plug(chip);
         self.sockets.push(socket);
+        // unwrap because we just pushed a value so there's no reason to get a None here
         self.sockets.last_mut().unwrap().clone()
     }
 
     /// Run the circuit for a certain amount of time
+    /// You must use `use_during` since it provides more accurate simulation by stepping
     pub fn run(&mut self, time_elapsed : std::time::Duration) {
         // TODO: find a way to update the traces accurately
         // current issue : the order of the traces affects the order of the links
@@ -52,6 +58,7 @@ impl Board {
     }
 
     /// Run the circuit for a certain amount of time segmented by a step
+    /// The smaller the step the more accurate the simulation will be.
     pub fn run_during(&mut self, duration: std::time::Duration, step: std::time::Duration) {
         let mut elapsed = std::time::Duration::new(0,0);
         while elapsed < duration {

src/chip/buttons.rs

@@ -1,3 +1,4 @@
+//! Buttons and other physically interactable chips
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;

src/chip/clocks.rs

@@ -1,3 +1,4 @@
+//! Clocks that pulse at different speeds
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;

src/chip/cpu.rs

@@ -1,3 +1,4 @@
+//! Central Processing Units
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;
@@ -118,7 +119,10 @@ use std::rc::Rc;
 /// STA (0xC1) | $1$2: address| Store the value of accumulator into address $1$2
 /// 
 /// # diagram
-/// IRQ: Interrupt Request
+/// IRQ: Interrupt Request (active low)
+/// RESET: Reset (active low)
+/// R/!W: Read Write mode
+/// CLOCK: Clock pin
 /// A0-9: Addresses
 /// IO0-7: Input/Output
 /// ```

src/chip/gates.rs

@@ -1,3 +1,4 @@
+//! Logic Gates like OR, AND, NOT ...
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;

src/chip/generators.rs

@@ -1,3 +1,4 @@
+//! Generators that provide fixed currents
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;

src/chip/memory.rs

@@ -1,3 +1,4 @@
+//! Readable and/or Writable Memory Chips
 use super::super::State;
 use super::{Pin, PinType, Chip};
 use std::cell::RefCell;
@@ -7,9 +8,9 @@ use rand::random;
 /// # A 256-bytes RAM chip
 /// 
 /// # Diagram
-/// CS: Chip Select
-/// WE: Write Enable
-/// OE: Output Enable
+/// CS: Chip Select (active low)
+/// WE: Write Enable (active low)
+/// OE: Output Enable (active low)
 /// A0-7: Addresses
 /// IO0-7: Input/Output
 /// ```
@@ -145,6 +146,7 @@ impl Chip for Ram256B {
             Err("Pin out of bounds")
         }
     }
+
     fn run(&mut self, _: std::time::Duration) {
         // check alimented
         if self.pin[10].borrow().state == State::Low && self.pin[21].borrow().state == State::High {
@@ -207,9 +209,8 @@ impl Chip for Ram256B {
 /// # A 256-bytes ROM chip
 /// 
 /// # Diagram
-/// CS: Chip Select
-/// WE: Write Enable
-/// OE: Output Enable
+/// CS: Chip Select (active low)
+/// OE: Output Enable (active low)
 /// A0-7: Addresses
 /// IO0-7: Input/Output
 /// ```

src/chip/mod.rs

@@ -1,3 +1,4 @@
+//! Chip trait, Pins and premade Chips
 use super::State;
 pub mod gates;
 pub mod generators;
@@ -7,14 +8,16 @@ pub mod clocks;
 use std::cell::RefCell;
 use std::rc::Rc;
 
+/// The type of a Pin, that can be Input or Output
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum PinType {
     Undefined,
     Input,
     Output,
-    // Both can cause issues on Trace::communicate()
+    // Both // removed because it can cause issues on Trace::communicate(). It's better to swap the pin when needed
 }
 
+/// A chip's Pin. Can be of type Input or Output, and holds a State
 #[derive(Debug)]
 pub struct Pin {
     pub number: u8,
@@ -31,17 +34,23 @@ impl Pin {
     }
 }
 
+/// Chip : a trait that represents chips on board
 pub trait Chip: std::fmt::Debug {
+    /// Runs the chip for a certain amount of time
     fn run(&mut self, elapsed_time: std::time::Duration);
+    /// Returns the number of pins the chip has
     fn get_pin_qty(&self) -> u8;
+    /// Get a pin of the chip
     fn get_pin(&mut self, pin: u8) -> Result<Rc<RefCell<Pin>>, &str>;
+    /// Get the state of the specified Pin
     fn get_pin_state(&mut self, pin: u8) -> State {
         if let Ok(pin) = self.get_pin(pin) {
             pin.borrow().state.clone()
         } else {
             State::Undefined
         }
     }
+    /// Set the state of the specified Pin
     fn set_pin_state(&mut self, pin: u8, state: &State) {
         if let Ok(pin) = self.get_pin(pin) {
             pin.borrow_mut().state = state.clone();

src/lib.rs

@@ -7,6 +7,7 @@ pub use board::Board;
 pub use trace::Trace;
 pub use socket::Socket;
 
+/// Current's State
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum State {
     Undefined,

src/socket.rs

@@ -2,6 +2,7 @@ use super::{Chip, Pin, PinType, State};
 use std::cell::RefCell;
 use std::rc::Rc;
 
+/// A Socket that holds a Chip
 #[derive(Default, Debug)]
 pub struct Socket {
     chip: Option<Box<dyn Chip>>,

src/trace.rs

@@ -2,6 +2,7 @@ use super::{Pin, PinType, State};
 use std::cell::RefCell;
 use std::rc::Rc;
 
+/// A Trace that connects two chip's Pin
 #[derive(Default, Debug)]
 pub struct Trace {
     link: Vec<Rc<RefCell<Pin>>>