Start more thorough documentation & renames

- Rename DeclarationPortInfo => DeclarationKind
- Rename WireInstance => Expression
- Rename UsedPort => SubModulePort
- Inline ConnectFrom into MultiplexerSource

src/block_vector.rs

@@ -2,15 +2,13 @@ use std::{cell::{UnsafeCell, Cell}, mem::MaybeUninit, ops::{DerefMut, Deref, Ind
 
 
 
-/* 
-    Has the property that appends don't move other elements. References are always preserved, therefore append is const 
-
-    Critically, alloc takes a CONST self, because using this will not invalidate any references derived from this
-    However, IndexMut still requires a mutable reference, since we can edit any arbitrary element, and the compiler can't check for overlap there
-
-    The const iterator exists, though it is not recommended to append elements while iterating over it. The const iterator would continue even onto newer elements
-    Existence of the mutable iterator disallows updating the container of course
-*/
+/// Has the property that appends don't move other elements. References are always preserved, therefore append is const 
+/// 
+/// Critically, alloc takes a CONST self, because using this will not invalidate any references derived from this
+/// However, IndexMut still requires a mutable reference, since we can edit any arbitrary element, and the compiler can't check for overlap there
+/// 
+/// The const iterator exists, though it is not recommended to append elements while iterating over it. The const iterator would continue even onto newer elements
+/// Existence of the mutable iterator disallows updating the container of course
 #[derive(Default)]
 pub struct BlockVec<T, const BLOCK_SIZE : usize = 64> {
     blocks : UnsafeCell<Vec<Box<[MaybeUninit<T>; BLOCK_SIZE]>>>,
@@ -58,6 +56,8 @@ impl<T, const BLOCK_SIZE : usize> BlockVec<T, BLOCK_SIZE> {
         self.length.get() == 0
     }
 
+    /// Critically, since appending to [BlockVec] is non-mutable, it is possible to do so while holding a [BlockVecIter].
+    /// BlockVecIter only iterates up to the size the BlockVec had when [BlockVec::iter] was called
     pub fn iter<'s>(&'s self) -> BlockVecIter<'s, T, BLOCK_SIZE> {
         self.into_iter()
     }

src/codegen/system_verilog.rs

@@ -4,7 +4,7 @@ use std::ops::Deref;
 use crate::linker::{IsExtern, LinkInfo};
 use crate::prelude::*;
 
-use crate::flattening::{DeclarationPortInfo, Instruction, Module, Port};
+use crate::flattening::{DeclarationKind, Instruction, Module, Port};
 use crate::instantiation::{
     InstantiatedModule, RealWire, RealWireDataSource, RealWirePathElem, CALCULATE_LATENCY_LATER,
 };
@@ -221,7 +221,7 @@ impl<'g, 'out, Stream: std::fmt::Write> CodeGenerationContext<'g, 'out, Stream>
                 &self.md.link_info.instructions[w.original_instruction]
             {
                 // Don't print named inputs and outputs, already did that in interface
-                if let DeclarationPortInfo::RegularPort { .. } = wire_decl.is_port {
+                if let DeclarationKind::RegularPort { .. } = wire_decl.decl_kind {
                     continue;
                 }
             }
@@ -364,9 +364,9 @@ impl<'g, 'out, Stream: std::fmt::Write> CodeGenerationContext<'g, 'out, Stream>
 
                     for s in sources {
                         let path = self.wire_ref_path_to_string(&s.to_path, w.absolute_latency);
-                        let from_name = self.wire_name(s.from.from, w.absolute_latency);
+                        let from_name = self.wire_name(s.from, w.absolute_latency);
                         self.program_text.write_char('\t').unwrap();
-                        for cond in s.from.condition.iter() {
+                        for cond in s.condition.iter() {
                             let cond_name = self.wire_name(cond.condition_wire, w.absolute_latency);
                             let invert = if cond.inverse { "!" } else { "" };
                             write!(self.program_text, "if({invert}{cond_name}) ").unwrap();

src/codegen/vhdl.rs

@@ -1,6 +1,6 @@
 
 use crate::{
-    flattening::{DeclarationPortInfo, Instruction}, linker::IsExtern, typing::concrete_type::ConcreteType, FlatAlloc, InstantiatedModule, Linker, Module, WireIDMarker
+    flattening::{DeclarationKind, Instruction}, linker::IsExtern, typing::concrete_type::ConcreteType, FlatAlloc, InstantiatedModule, Linker, Module, WireIDMarker
 };
 use std::ops::Deref;
 use std::fmt::Write;
@@ -137,7 +137,7 @@ impl<'g, 'out, Stream: std::fmt::Write> CodeGenerationContext<'g, 'out, Stream>
                 if let Instruction::Declaration(wire_decl) =
                     &self.md.link_info.instructions[wire.original_instruction]
                 {
-                    if let DeclarationPortInfo::RegularPort { .. } = wire_decl.is_port {
+                    if let DeclarationKind::RegularPort { .. } = wire_decl.decl_kind {
                         return false;
                     }
                 }

src/config.rs

@@ -27,6 +27,7 @@ pub enum TargetLanguage {
     VHDL,
 }
 
+/// All command-line flags are converted to this struct, of which the singleton instance can be acquired using [crate::config::config]
 #[derive(Debug, PartialEq, Eq)]
 pub struct ConfigStruct {
     pub use_lsp: bool,
@@ -175,6 +176,7 @@ where
     })
 }
 
+/// Access the singleton [ConfigStruct] representing the CLI arguments passed to `sus_compiler`
 pub fn config() -> &'static ConfigStruct {
     static CONFIG: LazyLock<ConfigStruct> = LazyLock::new(|| {
         parse_args(std::env::args_os())

src/dev_aid/lsp/hover_info.rs

@@ -5,7 +5,7 @@ use crate::to_string::pretty_print_concrete_instance;
 
 use lsp_types::{LanguageString, MarkedString};
 
-use crate::flattening::{DeclarationPortInfo, IdentifierType, InterfaceToDomainMap, Module};
+use crate::flattening::{DeclarationKind, IdentifierType, InterfaceToDomainMap, Module};
 use crate::instantiation::{SubModuleOrWire, CALCULATE_LATENCY_LATER};
 use crate::linker::{Documentation, FileData, LinkInfo, NameElem};
 
@@ -108,13 +108,13 @@ pub fn hover(info: LocationInfo, linker: &Linker, file_data: &FileData) -> Vec<M
             if let Some(ds) = &domain_str {
                 details_vec.push(ds);
             }
-            match decl.is_port {
-                DeclarationPortInfo::RegularPort {
+            match decl.decl_kind {
+                DeclarationKind::RegularPort {
                     is_input,
                     port_id: _,
                 } => details_vec.push(if is_input { "input" } else { "output" }),
-                DeclarationPortInfo::NotPort | DeclarationPortInfo::StructField { field_id:_ } => {}
-                DeclarationPortInfo::GenerativeInput(_) => details_vec.push("param"),
+                DeclarationKind::NotPort | DeclarationKind::StructField { field_id:_ } => {}
+                DeclarationKind::GenerativeInput(_) => details_vec.push("param"),
             }
 
             match decl.identifier_type {
@@ -203,7 +203,7 @@ pub fn hover(info: LocationInfo, linker: &Linker, file_data: &FileData) -> Vec<M
                         todo!("Non-module template args")
                     };
                     let md = &linker.modules[md_id];
-                    let decl = md.link_info.instructions[*declaration_instruction].unwrap_wire_declaration();
+                    let decl = md.link_info.instructions[*declaration_instruction].unwrap_declaration();
                     hover.sus_code(format!(
                         "param {} {}",
                         decl.typ_expr

src/dev_aid/lsp/tree_walk.rs

@@ -14,7 +14,7 @@ use crate::typing::template::{
 pub enum InModule<'linker> {
     NamedLocal(&'linker Declaration),
     NamedSubmodule(&'linker SubModuleInstance),
-    Temporary(&'linker WireInstance),
+    Temporary(&'linker Expression),
 }
 
 #[derive(Clone, Copy, Debug)]
@@ -56,17 +56,17 @@ impl<'linker> From<LocationInfo<'linker>> for RefersTo {
         match info {
             LocationInfo::InModule(md_id, md, flat_id, flat_obj) => match flat_obj {
                 InModule::NamedLocal(_) => {
-                    let decl = md.link_info.instructions[flat_id].unwrap_wire_declaration();
-                    match decl.is_port {
-                        DeclarationPortInfo::NotPort => {}
-                        DeclarationPortInfo::StructField { field_id:_ } => {}
-                        DeclarationPortInfo::RegularPort {
+                    let decl = md.link_info.instructions[flat_id].unwrap_declaration();
+                    match decl.decl_kind {
+                        DeclarationKind::NotPort => {}
+                        DeclarationKind::StructField { field_id:_ } => {}
+                        DeclarationKind::RegularPort {
                             is_input: _,
                             port_id,
                         } => {
                             result.port = Some((md_id, port_id));
                         }
-                        DeclarationPortInfo::GenerativeInput(template_id) => {
+                        DeclarationKind::GenerativeInput(template_id) => {
                             result.template_input = Some((NameElem::Module(md_id), template_id))
                         }
                     }
@@ -249,7 +249,7 @@ impl<'linker, Visitor: FnMut(Span, LocationInfo<'linker>), Pruner: Fn(Span) -> b
                         md_id,
                         md,
                         *decl_id,
-                        InModule::NamedLocal(md.link_info.instructions[*decl_id].unwrap_wire_declaration()),
+                        InModule::NamedLocal(md.link_info.instructions[*decl_id].unwrap_declaration()),
                     ),
                 );
             }
@@ -411,8 +411,8 @@ impl<'linker, Visitor: FnMut(Span, LocationInfo<'linker>), Pruner: Fn(Span) -> b
                             );
                         }
                     }
-                    Instruction::Wire(wire) => {
-                        if let WireSource::WireRef(wire_ref) = &wire.source {
+                    Instruction::Expression(wire) => {
+                        if let ExpressionSource::WireRef(wire_ref) = &wire.source {
                             self.walk_wire_ref(md_id, md, wire_ref);
                         } else {
                             self.visit(

src/errors.rs

@@ -13,13 +13,19 @@ pub enum ErrorLevel {
     Warning,
 }
 
+/// Represents a comment about a location in the source code.
+/// 
+/// Multiple infos can be attached to a single [CompileError]
 #[derive(Debug, Clone)]
 pub struct ErrorInfo {
     pub position: Span,
     pub file: FileUUID,
     pub info: String,
 }
 
+/// Represents an error or warning that the compiler produced. They can be shown in the IDE, or on the CLI
+/// 
+/// All errors for a single file are stored together, which is why this struct does not contain a FileUUID
 #[derive(Debug, Clone)]
 pub struct CompileError {
     pub position: Span,
@@ -30,7 +36,7 @@ pub struct CompileError {
 
 /// Stores all errors gathered within a context for reporting to the user.
 ///
-/// Only editable by converting to a ErrorCollector using [ErrorStore::take_for_editing]
+/// Only editable by converting to a ErrorCollector using [ErrorCollector::from_storage]
 #[derive(Debug, Clone)]
 pub struct ErrorStore {
     errors: Vec<CompileError>,
@@ -184,6 +190,11 @@ impl<'l> Drop for ErrorCollector<'l> {
     }
 }
 
+/// Intermediary struct to make adding infos far easier. 
+/// 
+/// Use as:
+/// 
+///     errors.warn(span, "Unused Variable").info(span2, file2, "In module").info(blablabla)
 pub struct ErrorReference<'ec> {
     err_collector: &'ec ErrorCollector<'ec>,
     pos: usize,

src/file_position.rs

@@ -5,7 +5,7 @@ use std::{
 
 use crate::prelude::FileUUID;
 
-// Span is defined as byte-byte idx. Start inclusive, end exclusive
+/// [Span] is defined as byte-byte idx. Start inclusive, end exclusive
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct Span(usize, usize);
 
@@ -76,6 +76,9 @@ impl Display for Span {
     }
 }
 
+/// A span for something that is between brackets. The assumption is that the brackets are 1 byte each. 
+/// 
+/// This struct is provided to improve readability on using these spans
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct BracketSpan(Span);