Merge pull request #381 from Pivot-Studio/griffin/improve/add-comments-5

improvement: add comments for builder

Author: Chronostasys

src/ast/builder/llvmbuilder.rs

@@ -924,6 +924,9 @@ impl<'a, 'ctx> LLVMBuilder<'a, 'ctx> {
         self.block_table.borrow().get(&handle).copied()
     }
 
+    /// # get_pri_basic_type
+    ///
+    /// get_pri_basic_type converts a pivot-lang primitive type into a llvm primitive type
     fn get_pri_basic_type(&self, tp: &PriType) -> BasicTypeEnum<'ctx> {
         match tp {
             PriType::I8 => self.context.i8_type().into(),
@@ -1686,6 +1689,10 @@ impl<'a, 'ctx> LLVMBuilder<'a, 'ctx> {
         *self.optimized.borrow_mut() = true;
     }
 
+    /// # try_load2var_inner
+    ///
+    /// it returns the element of a pointer,
+    /// or array, int, float, struct, vector, and function value rirectly
     fn try_load2var_inner(&self, v: usize, tp: &PLType, ctx: &mut Ctx<'a>) -> Result<usize, ()> {
         let handle = v;
         let v = self.get_llvm_value(handle).unwrap();
@@ -1694,7 +1701,6 @@ impl<'a, 'ctx> LLVMBuilder<'a, 'ctx> {
                 AnyValueEnum::ArrayValue(_)
                 | AnyValueEnum::IntValue(_)
                 | AnyValueEnum::FloatValue(_)
-                | AnyValueEnum::PointerValue(_)
                 | AnyValueEnum::StructValue(_)
                 | AnyValueEnum::VectorValue(_) => handle,
                 AnyValueEnum::FunctionValue(f) => {
@@ -1810,6 +1816,11 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
                 .as_debug_info_scope(),
         );
     }
+
+    /// # position_at_end_block
+    ///
+    /// Set the position of the builder to the end of a basic block refered
+    /// by the block handle.
     fn position_at_end_block(&self, block: BlockHandle) {
         self.builder
             .position_at_end(self.block_table.borrow()[&block]);
@@ -1829,7 +1840,6 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
             self.get_llvm_value_handle(&f.as_any_value_enum())
         }
     }
-
     fn get_or_add_global(
         &self,
         name: &str,
@@ -2032,6 +2042,10 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
     ) -> ValueHandle {
         self.alloc_with_f(name, pltype, ctx, declare, "DioGC__malloc_no_collect")
     }
+
+    /// # build_struct_gep
+    ///
+    /// it builds a GEP(GetElementPtr) instructions and returns the value handle of the instruction.
     fn build_struct_gep(
         &self,
         structv: ValueHandle,
@@ -2041,9 +2055,11 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
         ctx: &mut Ctx<'a>,
     ) -> Result<ValueHandle, String> {
         let structv = self.get_llvm_value(structv).unwrap();
-        let structv = structv.into_pointer_value();
+        let struct_val_ptr = structv.into_pointer_value();
         let sttp = self.get_basic_type_op(tp, ctx).unwrap();
-        let gep = self.builder.build_struct_gep(sttp, structv, index, name);
+        let gep = self
+            .builder
+            .build_struct_gep(sttp, struct_val_ptr, index, name);
         if let Ok(gep) = gep {
             return Ok(self.get_llvm_value_handle(&gep.as_any_value_enum()));
         } else {
@@ -2204,6 +2220,16 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
         // dbg.map(|d| self.builder.set_current_debug_location(d));
     }
 
+    /// # build_phi
+    ///
+    /// it emits the phi node of LLVM and sets up the phi node.
+    /// it returns the value handle of emitted phi node
+    ///
+    /// the pltype specifies the type of variable charged by the phi node.
+    /// for example, if a F64 is manupulated in different branches,
+    ///
+    /// the pltype will be F64.
+    /// the vbs holds a list of tuple which maps the block and value.
     fn build_phi(
         &self,
         pltype: &PLType,
@@ -2222,6 +2248,11 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
         self.get_llvm_value_handle(&phi.as_any_value_enum())
     }
 
+    /// # build_unconditional_branch
+    ///
+    /// builds a unconditional branch by the value refered by the block handle to
+    /// terminates the current block of the builder, which adds a new block in the
+    /// builder as well.
     fn build_unconditional_branch(&self, bb: BlockHandle) {
         let bb = self.get_llvm_block(bb).unwrap();
         self.builder.build_unconditional_branch(bb).unwrap();
@@ -2266,6 +2297,7 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
         // run_immix_pass(self.module);
         self.module.write_bitcode_to_path(path)
     }
+
     fn int_value(&self, ty: &PriType, v: u64, sign_ext: bool) -> ValueHandle {
         let ty = self.get_pri_basic_type(ty).into_int_type();
         let v = ty.const_int(v, sign_ext);
@@ -2431,6 +2463,11 @@ impl<'a, 'ctx> IRBuilder<'a, 'ctx> for LLVMBuilder<'a, 'ctx> {
         let v = self.builder.build_int_truncate(v, dest_ty, name).unwrap();
         self.get_llvm_value_handle(&v.as_any_value_enum())
     }
+
+    /// # build_conditional_branch
+    ///
+    /// it helps to build a conditional branch by the condition, then bacis block and else block
+    /// refered by the value handle and block handles.
     fn build_conditional_branch(
         &self,
         cond: ValueHandle,

src/ast/builder/mod.rs

@@ -124,6 +124,11 @@ pub trait IRBuilder<'a, 'ctx> {
         v: ValueHandle,
         ctx: &mut Ctx<'a>,
     );
+
+    /// # int_value
+    ///
+    /// int_value converts the [PriType] value into a integer format to emit code,
+    /// ,stores the emitted value into the builder and returns its value handle.
     fn int_value(&self, ty: &PriType, v: u64, sign_ext: bool) -> ValueHandle;
     fn position_at(&self, v: ValueHandle);
     fn print_to_file(&self, file: &Path) -> Result<(), String>;
@@ -137,6 +142,11 @@ pub trait IRBuilder<'a, 'ctx> {
         vbs: &[(ValueHandle, BlockHandle)],
     ) -> ValueHandle;
     fn build_unconditional_branch(&self, bb: BlockHandle);
+
+    /// # position_at_end_block
+    ///
+    /// Set the position of the builder to the end of a basic block refered
+    /// by the block handle.
     fn position_at_end_block(&self, block: BlockHandle);
     fn add_body_to_struct_type(&self, name: &str, sttype: &STType, ctx: &mut Ctx<'a>);
     fn get_or_insert_fn_handle(&self, pltp: &FNValue, ctx: &mut Ctx<'a>) -> (ValueHandle, bool);
@@ -154,6 +164,11 @@ pub trait IRBuilder<'a, 'ctx> {
         tp: &PLType,
         ctx: &mut Ctx<'a>,
     ) -> ValueHandle;
+
+    /// # try_load2var
+    ///
+    /// it returns the element of a pointer,
+    /// or array, int, float, struct, vector, and function value directly
     fn try_load2var(
         &self,
         range: Range,

src/ast/ctx.rs

@@ -942,7 +942,10 @@ impl<'a, 'ctx> Ctx<'a> {
         self.diagnose.borrow_mut().insert(dia);
         dia2
     }
-    // load type* to type
+    /// # try_load2var
+    ///
+    /// load the element of a pointer from the builder,
+    /// or get the ordinary types for the others
     pub fn try_load2var<'b>(
         &'b mut self,
         range: Range,
@@ -1067,6 +1070,11 @@ impl<'a, 'ctx> Ctx<'a> {
     pub fn get_location(&self, range: Range) -> Location {
         Location::new(self.get_file_url(), range.to_diag_range())
     }
+
+    /// # position_at_end
+    ///
+    /// it replace its current block field with the input block handle,
+    /// and inserts it at the end of current builder
     pub fn position_at_end<'b>(
         &'b mut self,
         block: BlockHandle,
@@ -1076,9 +1084,10 @@ impl<'a, 'ctx> Ctx<'a> {
         builder.position_at_end_block(block);
     }
 
-    /// # auto_deref
-    /// 自动解引用，有几层解几层
-    pub fn auto_deref<'b>(
+    /// # deref_greedily
+    ///
+    /// it de-references greedily until the result cannot be de-referenced anymore.
+    pub fn deref_greedily<'b>(
         &'b mut self,
         tp: Arc<RefCell<PLType>>,
         value: ValueHandle,

src/ast/ctx/builtins.rs

@@ -724,9 +724,9 @@ fn emit_for_fields<'a, 'b>(
         let tp = g.get_ty();
         let tp = get_type_deep(tp);
         let v = g.get_value();
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let tp = get_type_deep(tp);
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let mut code_gen = false;
         let stp = match &*tp.borrow() {
             PLType::Struct(_) => {
@@ -836,9 +836,9 @@ fn emit_if_arr<'a, 'b>(
         let tp = g.get_ty();
         let tp = get_type_deep(tp);
         let v = g.get_value();
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let tp = get_type_deep(tp);
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let mut code_gen = false;
         let stp = match &*tp.borrow() {
             PLType::Arr(_) => {
@@ -926,9 +926,9 @@ fn emit_if_union<'a, 'b>(
         let tp = g.get_ty();
         let tp = get_type_deep(tp);
         let v = g.get_value();
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let tp = get_type_deep(tp);
-        let (tp, v) = ctx.auto_deref(tp, v, builder);
+        let (tp, v) = ctx.deref_greedily(tp, v, builder);
         let mut code_gen = false;
         let stp = match &*tp.borrow() {
             PLType::Union(_) => {
@@ -1074,7 +1074,7 @@ fn emit_match_type<'a, 'b>(
     if let Some(g) = &v {
         let tp = g.get_ty();
         let v = g.get_value();
-        let (tp, mut v) = ctx.auto_deref(tp, v, builder);
+        let (tp, mut v) = ctx.deref_greedily(tp, v, builder);
         let tp = get_type_deep(tp);
         if tp != generic {
             // 类型不匹配

src/ast/ctx/cast.rs

@@ -331,7 +331,7 @@ impl<'a, 'ctx> Ctx<'a> {
                 }
             }
         }
-        let (st_pltype, st_value) = self.auto_deref(ori_pltype, ori_value, builder);
+        let (st_pltype, st_value) = self.deref_greedily(ori_pltype, ori_value, builder);
         if let PLType::Trait(t) = &*target_pltype.borrow() {
             for f in t.list_trait_fields().iter() {
                 if let TypeNodeEnum::Func(fu) = &*f.typenode {

src/ast/node/control.rs

@@ -47,59 +47,84 @@ impl Node for IfNode {
         let cond_block = builder.append_basic_block(ctx.function.unwrap(), "if.cond");
         let then_block = builder.append_basic_block(ctx.function.unwrap(), "if.then");
         let else_block = builder.append_basic_block(ctx.function.unwrap(), "if.else");
-        let after_block = builder.append_basic_block(ctx.function.unwrap(), "if.after");
+        let merge_block = builder.append_basic_block(ctx.function.unwrap(), "if.after");
         builder.build_unconditional_branch(cond_block);
         ctx.position_at_end(cond_block, builder);
-        let condrange = self.cond.range();
-        let v = self.cond.emit(ctx, builder)?.get_value();
-        let code = ErrorCode::IF_CONDITION_MUST_BE_BOOL;
-        check_bool(&v, ctx, condrange, code)?;
-        let v = v.unwrap();
+
+        let cond_range = self.cond.range();
+        let cond_val = self.cond.emit(ctx, builder)?.get_value();
+        check_bool(
+            &cond_val,
+            ctx,
+            cond_range,
+            ErrorCode::IF_CONDITION_MUST_BE_BOOL,
+        )?;
+
+        let v = cond_val.unwrap();
         let cond = v.get_value();
-        let cond = ctx.try_load2var(condrange, cond, builder, &v.get_ty().borrow())?;
+        let cond = ctx.try_load2var(cond_range, cond, builder, &v.get_ty().borrow())?;
         let cond = builder.build_int_truncate(cond, &PriType::BOOL, "trunctemp");
+
+        //
         builder.build_conditional_branch(cond, then_block, else_block);
-        // then block
+
+        // emit the else logic into the then block
         ctx.position_at_end(then_block, builder);
+        // emit the code inside a child context because it belongs to a sub-block
         let then_terminator = self.then.emit_child(ctx, builder)?.get_term();
         if then_terminator.is_none() {
-            builder.build_unconditional_branch(after_block);
+            // there is no terminator(like return, yield and so forth) in the statement
+            // create an unconditional branch to merge block to finish off the "then" block
+            builder.build_unconditional_branch(merge_block);
         }
+
+        // emit the else logic into the else block
         ctx.position_at_end(else_block, builder);
         let terminator = if let Some(el) = &mut self.els {
             let mut child = ctx.new_child(el.range().start, builder);
             let else_terminator = el.emit(&mut child, builder)?.get_term();
             if else_terminator.is_none() {
-                builder.build_unconditional_branch(after_block);
+                // create an unconditional branch only if no terminator is detected
+                // otherwise, the code to be executed might be the others instead of merge block
+                // for example, if there is a 'return' statement in the if-then-else clause,
+                // it won't execute the merge block as it returns directly
+                builder.build_unconditional_branch(merge_block);
             }
+
             if then_terminator.is_return() && else_terminator.is_return() {
                 TerminatorEnum::Return
             } else {
                 TerminatorEnum::None
             }
         } else {
-            builder.build_unconditional_branch(after_block);
+            builder.build_unconditional_branch(merge_block);
             TerminatorEnum::None
         };
-        ctx.position_at_end(after_block, builder);
+
+        ctx.position_at_end(merge_block, builder);
         if terminator.is_return() {
-            builder.build_unconditional_branch(after_block);
+            builder.build_unconditional_branch(merge_block);
         }
         ctx.emit_comment_highlight(&self.comments[0]);
+
         NodeOutput::default().with_term(terminator).to_result()
     }
     // ANCHOR_END: emit
 }
 
+/// # check_bool
+///
+/// it ensures the input NodeValue represents a [PriType::BOOL],
+/// otheriwse it returns an error with the range and error code.
 fn check_bool(
     v: &Option<NodeValue>,
     ctx: &mut Ctx,
-    condrange: Range,
+    range: Range,
     code: ErrorCode,
 ) -> Result<(), PLDiag> {
     if v.is_none() || !v.as_ref().unwrap().get_ty().borrow().is(&PriType::BOOL) {
         return Err(ctx.add_diag(
-            condrange
+            range
                 .new_err(code)
                 .add_help("use a bool variable instead")
                 .clone(),

src/ast/node/mod.rs

@@ -170,6 +170,7 @@ pub trait Node: RangeTrait + FmtTrait + PrintTrait {
     ) -> NodeResult;
 }
 
+/// print trait to report the AST node structure
 #[enum_dispatch]
 pub trait PrintTrait {
     fn print(&self, tabs: usize, end: bool, line: Vec<bool>);
@@ -186,6 +187,7 @@ pub enum Num {
 impl Eq for Num {
     // FIXME: NaN https://stackoverflow.com/questions/39638363/how-can-i-use-a-hashmap-with-f64-as-key-in-rust
 }
+
 #[macro_export]
 macro_rules! mismatch_err {
     ($ctx:ident, $range:expr,$exprange:expr, $expect:expr,$got:expr) => {

src/ast/node/node_result.rs

@@ -35,12 +35,16 @@ pub trait NodeResultBuilder {
 }
 
 impl NodeResultBuilder for ValueHandle {
+    /// new_output returns a [NodeOutput] with the type and its value handle
     fn new_output(&self, typ: Arc<RefCell<PLType>>) -> NodeOutput {
         NodeOutput::new_value_simple(*self, typ)
     }
 }
 
 impl NodeOutput {
+    /// # set_const
+    ///
+    /// set_const marks a node refered by handle value is immutable
     pub fn set_const(&mut self) -> &mut Self {
         if let Some(value) = &mut self.value {
             value.set_const(true);
@@ -71,6 +75,9 @@ impl NodeOutput {
         self
     }
 
+    /// # to_result
+    ///
+    /// to_result returns a cloned version of [NodeResult]
     pub fn to_result(&self) -> NodeResult {
         Ok(self.clone())
     }