docs(ir): discipline comments per comment spec

src/ir/gen.rs

@@ -1,8 +1,8 @@
-// `conversions` is module-private within `gen` by default, but we
-// surface it to the parent `ir` module (via `pub(super)`) so that
-// `src/ir.rs` can re-export `compose_var_def_dtype` for the
-// feature-gated `experimental` layer.  Items inside still control
-// their own visibility — nothing else leaks.
+// `conversions` stays private to `gen` apart from `pub(super)`, which
+// surfaces it to the parent `ir` module so that `src/ir.rs` can
+// re-export `compose_var_def_dtype` for the feature-gated
+// `experimental` layer.  Items inside still control their own
+// visibility — nothing else leaks.
 pub(super) mod conversions;
 mod function_gen;
 mod module_gen;

src/ir/gen/conversions.rs

@@ -8,15 +8,10 @@
 use crate::ast;
 use crate::ir::types::Dtype;
 
-/// Converts an optional AST type specifier into the corresponding base IR data type (`Dtype`).
-///
-/// Delegates to `Dtype::from(&TypeSpecifier)` when a specifier is present;
-/// defaults to `Dtype::I32` when absent.
-///
-/// This function is used for **global variables** and **function parameters** where
-/// an absent type annotation defaults to `i32`.  Local variables are handled by the
-/// separate type inference pass (`type_infer::infer_function`), which resolves their
-/// types before IR generation.
+/// Base [`Dtype`] for **global variables** and **function parameters**, where
+/// an absent type annotation defaults to `i32`.  Local variables get their
+/// types from the separate inference pass (`type_infer::infer_function`)
+/// before IR generation.
 fn base_dtype(type_specifier: Option<&ast::TypeSpecifier>) -> Dtype {
     type_specifier.map_or(Dtype::I32, Dtype::from)
 }
@@ -43,12 +38,6 @@ pub(crate) fn compose_var_def_dtype(base: Dtype, inner: &ast::VarDefInner) -> Dt
     }
 }
 
-// ---------------------------------------------------------------------------
-// `From` trait implementations: AST TypeSpecifier -> IR Dtype
-// ---------------------------------------------------------------------------
-//
-// These provide infallible conversions from AST type specifiers to IR types.
-
 /// Converts an owned `ast::TypeSpecifier` into a `Dtype` by delegating to the
 /// by-reference implementation.
 impl From<ast::TypeSpecifier> for Dtype {
@@ -78,18 +67,7 @@ impl From<&ast::TypeSpecifier> for Dtype {
     }
 }
 
-// ---------------------------------------------------------------------------
-// `TryFrom` trait implementations: AST declarations -> IR Dtype
-// ---------------------------------------------------------------------------
-//
-// These are fallible conversions because certain combinations (e.g., struct
-// definitions with initializers) are not supported and produce an error.
-
-/// Converts a variable declaration (`VarDecl`) to its IR data type.
-///
-/// First resolves the base type from the optional type specifier, then wraps it
-/// in an array type if the declaration is for an array (with a known length),
-/// or returns the base type directly for scalar declarations.
+/// Storage [`Dtype`] of a global-variable or function-parameter declaration.
 impl TryFrom<&ast::VarDecl> for Dtype {
     type Error = crate::ir::Error;
 
@@ -101,9 +79,9 @@ impl TryFrom<&ast::VarDecl> for Dtype {
 
 /// Converts a variable definition (`VarDef`) to its IR data type.
 ///
-/// Similar to the `VarDecl` conversion, but additionally rejects struct types
-/// with initializers—struct variables cannot be initialized inline, so
-/// attempting to do so returns `Error::StructInitialization`.
+/// Rejects struct-typed definitions: a `VarDef` always carries an initializer
+/// and struct variables cannot be initialized inline, so the conversion
+/// returns `Error::StructInitialization`.
 impl TryFrom<&ast::VarDef> for Dtype {
     type Error = crate::ir::Error;
 
@@ -116,10 +94,8 @@ impl TryFrom<&ast::VarDef> for Dtype {
     }
 }
 
-/// Converts a variable declaration statement (`VarDeclStmt`) to its IR data type.
-///
-/// Delegates to the `TryFrom<&VarDecl>` or `TryFrom<&VarDef>` implementation
-/// depending on whether the statement is a pure declaration or a definition.
+/// Converts a variable declaration statement (`VarDeclStmt`) to its IR data
+/// type — the entry point used when typing global variables.
 impl TryFrom<&ast::VarDeclStmt> for Dtype {
     type Error = crate::ir::Error;
 

src/ir/value.rs

@@ -84,8 +84,8 @@ impl Display for GlobalRef {
 
 /// A typed integer constant operand.
 ///
-/// The value is stored as `i64` to leave room for constants wider than i32
-/// (e.g. pointer-sized indices) once the IR supports them.
+/// The value is stored as `i64` to leave room for constants wider than `i32`
+/// (e.g. pointer-sized indices).
 #[derive(Clone)]
 pub struct IntConst {
     pub dtype: Dtype,
@@ -131,7 +131,7 @@ impl Operand {
 
     /// True for any operand other than an integer constant — i.e. anything
     /// that denotes a named vreg or a global symbol and could therefore
-    /// hold an address.  The front-end pairs this predicate with a
+    /// hold an address.  IR lowering pairs this predicate with a
     /// separate `Dtype::Pointer` check to decide whether to insert an
     /// implicit load at a value-use site.
     pub fn is_addressable(&self) -> bool {