Add comments & refactoring

compiler/erg_compiler/codegen.rs

@@ -71,7 +71,7 @@ fn escape_name(ident: Identifier) -> Str {
 }
 
 #[derive(Debug, Clone)]
-pub struct CodeGenUnit {
+pub struct PyCodeGenUnit {
     pub(crate) id: usize,
     pub(crate) py_version: PythonVersion,
     pub(crate) codeobj: CodeObj,
@@ -82,14 +82,14 @@ pub struct CodeGenUnit {
     pub(crate) _refs: Vec<ValueObj>, // ref-counted objects
 }
 
-impl PartialEq for CodeGenUnit {
+impl PartialEq for PyCodeGenUnit {
     #[inline]
     fn eq(&self, other: &Self) -> bool {
         self.id == other.id
     }
 }
 
-impl fmt::Display for CodeGenUnit {
+impl fmt::Display for PyCodeGenUnit {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
@@ -100,7 +100,7 @@ impl fmt::Display for CodeGenUnit {
     }
 }
 
-impl CodeGenUnit {
+impl PyCodeGenUnit {
     pub fn new<S: Into<Str>, T: Into<Str>>(
         id: usize,
         py_version: PythonVersion,
@@ -123,12 +123,12 @@ impl CodeGenUnit {
 }
 
 #[derive(Debug, Clone)]
-pub struct CodeGenStack(Vec<CodeGenUnit>);
+pub struct PyCodeGenStack(Vec<PyCodeGenUnit>);
 
-impl_stream_for_wrapper!(CodeGenStack, CodeGenUnit);
+impl_stream_for_wrapper!(PyCodeGenStack, PyCodeGenUnit);
 
 #[derive(Debug)]
-pub struct CodeGenerator {
+pub struct PyCodeGenerator {
     cfg: ErgConfig,
     pub(crate) py_version: PythonVersion,
     str_cache: CacheSet<str>,
@@ -138,10 +138,10 @@ pub struct CodeGenerator {
     module_type_loaded: bool,
     abc_loaded: bool,
     unit_size: usize,
-    units: CodeGenStack,
+    units: PyCodeGenStack,
 }
 
-impl CodeGenerator {
+impl PyCodeGenerator {
     pub fn new(cfg: ErgConfig) -> Self {
         Self {
             py_version: cfg.target_version.unwrap_or_else(env_python_version),
@@ -153,7 +153,7 @@ impl CodeGenerator {
             module_type_loaded: false,
             abc_loaded: false,
             unit_size: 0,
-            units: CodeGenStack::empty(),
+            units: PyCodeGenStack::empty(),
         }
     }
 
@@ -172,17 +172,17 @@ impl CodeGenerator {
 
     /// 大抵の場合はモジュールのブロックが返る
     #[inline]
-    fn toplevel_block(&self) -> &CodeGenUnit {
+    fn toplevel_block(&self) -> &PyCodeGenUnit {
         self.units.first().unwrap()
     }
 
     #[inline]
-    fn cur_block(&self) -> &CodeGenUnit {
+    fn cur_block(&self) -> &PyCodeGenUnit {
         self.units.last().unwrap()
     }
 
     #[inline]
-    fn mut_cur_block(&mut self) -> &mut CodeGenUnit {
+    fn mut_cur_block(&mut self) -> &mut PyCodeGenUnit {
         self.units.last_mut().unwrap()
     }
 
@@ -923,7 +923,7 @@ impl CodeGenerator {
             .get(0)
             .and_then(|def| def.ln_begin())
             .unwrap_or_else(|| sig.ln_begin().unwrap());
-        self.units.push(CodeGenUnit::new(
+        self.units.push(PyCodeGenUnit::new(
             self.unit_size,
             self.py_version,
             vec![],
@@ -991,7 +991,7 @@ impl CodeGenerator {
         }
         let code = {
             self.unit_size += 1;
-            self.units.push(CodeGenUnit::new(
+            self.units.push(PyCodeGenUnit::new(
                 self.unit_size,
                 self.py_version,
                 vec![],
@@ -2288,7 +2288,7 @@ impl CodeGenerator {
             Some(l) => l,
             None => class.sig.ln_begin().unwrap(),
         };
-        self.units.push(CodeGenUnit::new(
+        self.units.push(PyCodeGenUnit::new(
             self.unit_size,
             self.py_version,
             vec![],
@@ -2436,7 +2436,7 @@ impl CodeGenerator {
             .first()
             .and_then(|first| first.ln_begin())
             .unwrap_or(0);
-        self.units.push(CodeGenUnit::new(
+        self.units.push(PyCodeGenUnit::new(
             self.unit_size,
             self.py_version,
             params,
@@ -2588,7 +2588,7 @@ impl CodeGenerator {
     pub fn emit(&mut self, hir: HIR) -> CodeObj {
         log!(info "the code-generating process has started.{RESET}");
         self.unit_size += 1;
-        self.units.push(CodeGenUnit::new(
+        self.units.push(PyCodeGenUnit::new(
             self.unit_size,
             self.py_version,
             vec![],

compiler/erg_compiler/compile.rs

@@ -10,7 +10,7 @@ use erg_common::traits::{Runnable, Stream};
 use crate::ty::codeobj::CodeObj;
 
 use crate::build_hir::HIRBuilder;
-use crate::codegen::CodeGenerator;
+use crate::codegen::PyCodeGenerator;
 use crate::desugar_hir::HIRDesugarer;
 use crate::error::{CompileError, CompileErrors};
 use crate::hir::{Expr, HIR};
@@ -96,7 +96,7 @@ pub struct Compiler {
     pub cfg: ErgConfig,
     builder: HIRBuilder,
     mod_cache: SharedModuleCache,
-    code_generator: CodeGenerator,
+    code_generator: PyCodeGenerator,
 }
 
 impl Runnable for Compiler {
@@ -114,7 +114,7 @@ impl Runnable for Compiler {
                 mod_cache.clone(),
                 py_mod_cache,
             ),
-            code_generator: CodeGenerator::new(cfg.copy()),
+            code_generator: PyCodeGenerator::new(cfg.copy()),
             mod_cache,
             cfg,
         }

compiler/erg_compiler/context/cache.rs

@@ -19,6 +19,9 @@ impl SubtypePair {
     }
 }
 
+/// Caches type relationships.
+/// The cost of searching for subtype relations of a class, for example, is not small.
+/// Some relationships are cached because they tend to be queried many times.
 #[derive(Debug, Default)]
 pub struct TypeCmpCache {
     cache: Dict<SubtypePair, bool>,

compiler/erg_compiler/context/tyvar.rs

@@ -26,7 +26,6 @@ use Variance::*;
 impl Context {
     pub const TOP_LEVEL: usize = 1;
 
-    /// 型を非依存化する
     fn _independentise(_t: Type, _ts: &[Type]) -> Type {
         todo!()
     }

compiler/erg_compiler/desugar_hir.rs

@@ -3,6 +3,7 @@ use erg_common::traits::Stream;
 
 use crate::hir::{Accessor, AttrDef, Block, Expr, HIR};
 
+/// Desugares HIR to make it more like Python semantics.
 pub struct HIRDesugarer {}
 
 impl HIRDesugarer {

compiler/erg_compiler/effectcheck.rs

@@ -28,6 +28,10 @@ enum BlockKind {
 
 use BlockKind::*;
 
+/// Checks code for side effects.
+/// For example:
+/// * check if expressions with side effects are not used in functions
+/// * check if methods that change internal state are not defined in immutable classes
 #[derive(Debug)]
 pub struct SideEffectChecker {
     cfg: ErgConfig,

compiler/erg_compiler/hir.rs

@@ -1925,6 +1925,8 @@ impl Locational for Module {
 
 impl_stream_for_wrapper!(Module, Expr);
 
+/// High-level Intermediate Representation
+/// AST with type information added
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct HIR {
     pub name: Str,

compiler/erg_compiler/link.rs

@@ -18,6 +18,8 @@ use crate::ty::HasType;
 use crate::hir::*;
 use crate::mod_cache::SharedModuleCache;
 
+/// Link code using the module cache.
+/// Erg links all non-Python modules into a single pyc file.
 pub struct Linker<'a> {
     cfg: &'a ErgConfig,
     mod_cache: &'a SharedModuleCache,

compiler/erg_compiler/lower.rs

@@ -41,7 +41,7 @@ use crate::varinfo::{Mutability, VarInfo, VarKind};
 use crate::AccessKind;
 use Visibility::*;
 
-/// Singleton that checks types of an AST, and convert (lower) it into a HIR
+/// Checks & infers types of an AST, and convert (lower) it into a HIR
 #[derive(Debug)]
 pub struct ASTLowerer {
     cfg: ErgConfig,

compiler/erg_compiler/mod_cache.rs

@@ -62,6 +62,9 @@ impl ModuleEntry {
     }
 }
 
+/// Caches checked modules.
+/// In addition to being queried here when re-imported, it is also used when linking
+/// (Erg links all scripts defined in erg and outputs them to a single pyc file).
 #[derive(Debug, Default)]
 pub struct ModuleCache {
     cache: Dict<PathBuf, ModuleEntry>,

compiler/erg_compiler/ownercheck.rs

@@ -28,6 +28,10 @@ struct LocalVars {
     dropped_vars: Dict<Str, Location>,
 }
 
+/// Check code ownership.
+/// for example:
+/// * Check if moved variables are not used again.
+/// * Checks whether a mutable reference method is called in an immutable reference method.
 #[derive(Debug)]
 pub struct OwnershipChecker {
     cfg: ErgConfig,

compiler/erg_compiler/varinfo.rs

@@ -36,6 +36,7 @@ impl Mutability {
 
 use Mutability::*;
 
+/// TODO: removed in the future
 /// e.g.
 /// ```python
 /// K(T, [U, V]) = ...