From 3ec19a92958b695dd212d13af8bd5fad58326dc3 Mon Sep 17 00:00:00 2001 From: Yi Sun Date: Sat, 1 Aug 2026 18:39:53 +0800 Subject: [PATCH] docs(ir): discipline comments per comment spec - removed 2 divider banners with their trailing section restatements (spec 5.4, 9.3) in gen/conversions.rs - rewrote 5 restatement/narration doc comments (spec 2.1, 2.2) in gen/conversions.rs: base_dtype, TryFrom<&VarDecl>, TryFrom<&VarDef>, TryFrom<&VarDeclStmt>; kept the i32-default rule and the struct-rejection rationale - rewrote 1 future-tense aside (spec 3.1): IntConst i64 headroom in value.rs - rewrote 1 first-person voice comment (spec 5.5): pub(super) module comment in gen.rs, factual content unchanged - fixed 1 imprecise referent (spec 8.3): 'the front-end' -> IR lowering on Operand::is_addressable No commented-out code blocks and no annotation tags in scope; comment-only diff, no code lines touched. --- src/ir/gen.rs | 10 ++++----- src/ir/gen/conversions.rs | 44 +++++++++------------------------------ src/ir/value.rs | 6 +++--- 3 files changed, 18 insertions(+), 42 deletions(-) diff --git a/src/ir/gen.rs b/src/ir/gen.rs index 35ce5dd..32ba571 100644 --- a/src/ir/gen.rs +++ b/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; diff --git a/src/ir/gen/conversions.rs b/src/ir/gen/conversions.rs index 62b3af7..c3dff24 100644 --- a/src/ir/gen/conversions.rs +++ b/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 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; diff --git a/src/ir/value.rs b/src/ir/value.rs index e0165da..5660c89 100644 --- a/src/ir/value.rs +++ b/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 {