docs: Enhance module documentation across various files for clarity a… (#62)

* docs: Enhance module documentation across various files for clarity and completeness

* fix: Remove unnecessary blank line in build.rs for cleaner code

* docs: Update documentation to improve clarity and consistency in code comments

src/ssa/heap.rs

@@ -10,7 +10,7 @@
 //! - PointsToSet is bounded to `analysis.engine.max_pointsto` entries
 //!   (default 32, widening on overflow, see [`effective_max_pointsto`]).
 //!   Overflow drops emit an [`crate::engine_notes::EngineNote::PointsToTruncated`]
-//!   note and increment [`POINTSTO_TRUNCATION_COUNT`] so operators can
+//!   note and increment `POINTSTO_TRUNCATION_COUNT` so operators can
 //!   tell when the cap is firing on their corpus.
 //! - HeapState tracks per-(heap-object, slot) taint (monotone lattice)
 //!   - HeapSlot::Index(u64) for constant-index container access (proven by const propagation)
@@ -168,7 +168,7 @@ impl PointsToSet {
     ///
     /// Truncates to [`effective_max_pointsto`]; any heap-object member
     /// that would be admitted after the cap is reached is dropped and
-    /// counted via [`record_pointsto_truncation`].  Truncation is
+    /// counted via `record_pointsto_truncation`.  Truncation is
     /// deterministic: the merge proceeds in sorted order, so survivors
     /// are always the smallest `HeapObjectId`s across the two inputs.
     pub fn union(&self, other: &Self) -> Self {
@@ -230,7 +230,7 @@ impl PointsToSet {
     ///
     /// When the set is already at [`effective_max_pointsto`], the new id
     /// is dropped and the drop is counted via
-    /// [`record_pointsto_truncation`].
+    /// `record_pointsto_truncation`.
     pub fn insert(&mut self, id: HeapObjectId) {
         match self.ids.binary_search(&id) {
             Ok(_) => {} // already present

src/ssa/mod.rs

@@ -1,3 +1,21 @@
+//! SSA IR, lowering, and optimization passes.
+//!
+//! The pipeline converts a CFG into a pruned SSA body consumed by the taint
+//! analysis engine. [`lower_to_ssa`] inserts phi nodes via Cytron's algorithm
+//! and renames variables along the dominator tree. [`optimize_ssa`] runs
+//! constant propagation, branch pruning, copy propagation, DCE, and type
+//! fact analysis in sequence.
+//!
+//! Key submodules:
+//! - [`ir`]: core types (`SsaValue`, `SsaOp`, `SsaInst`, `SsaBlock`, `SsaBody`)
+//! - [`lower`]: CFG-to-SSA lowering with Cytron phi insertion and dominator-tree rename
+//! - [`const_prop`]: sparse conditional constant propagation with branch pruning
+//! - [`copy_prop`]: copy and alias propagation
+//! - [`dce`]: dead definition elimination
+//! - [`type_facts`]: per-value type inference (`TypeKind`, `TypeFactResult`)
+//! - [`heap`]: abstract heap for container element abstractions
+//! - [`alias`]: base-variable alias groups from copy propagation
+
 #[allow(dead_code)] // IR types, fields used by Display impl, tests, and downstream analyses
 pub mod alias;
 pub mod const_prop;

src/ssa/param_points_to.rs

@@ -25,7 +25,7 @@
 //!
 //! The analysis is **flow-insensitive** and **bounded**: it does not
 //! reason about path feasibility, and it stops adding edges once the
-//! summary's [`MAX_ALIAS_EDGES`] cap is reached, the overflow flag is
+//! summary's `MAX_ALIAS_EDGES` cap is reached, the overflow flag is
 //! the conservative fallback that callers honour.
 
 use std::collections::{HashMap, HashSet};
@@ -239,7 +239,7 @@ fn returns_fresh_allocation(
 /// `formal_param_count` bounds the parameter indices written to the
 /// summary: scoped lowering synthesises `Param` ops for module-level
 /// captures at indices beyond the formal arity, and those must not leak
-/// into the summary (they would trip [`crate::summary::ssa_summary_fits_arity`]).
+/// into the summary (they would trip `ssa_summary_fits_arity`).
 pub fn analyse_param_points_to(
     ssa: &SsaBody,
     param_info: &[(usize, String, SsaValue)],