core: further document BuiltinBuilder

nac3core/src/toplevel/builtins.rs

@@ -14,7 +14,10 @@ use strum::IntoEnumIterator;
 use crate::{
     codegen::{
         builtin_fns,
-        classes::{ArrayLikeValue, NDArrayValue, ProxyType, ProxyValue, RangeType, RangeValue, TypedArrayLikeAccessor},
+        classes::{
+            ArrayLikeValue, NDArrayValue, ProxyType, ProxyValue, RangeType, RangeValue,
+            TypedArrayLikeAccessor,
+        },
         expr::destructure_range,
         irrt::*,
         numpy::*,
@@ -436,6 +439,7 @@ impl<'a> BuiltinBuilder<'a> {
         PrimDef::iter().map(|prim| self.build_builtin_of_prim(prim)).collect_vec()
     }
 
+    /// Build the [`TopLevelDef`] associated of a [`PrimDef`].
     fn build_builtin_of_prim(&mut self, prim: PrimDef) -> TopLevelDef {
         match prim {
             PrimDef::Int32
@@ -543,6 +547,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build "simple" primitive classes.
     fn build_simple_primitive_class(&self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -562,6 +567,7 @@ impl<'a> BuiltinBuilder<'a> {
         TopLevelComposer::make_top_level_class_def(prim.id(), None, prim.name().into(), None, None)
     }
 
+    /// Build the class `Exception` and its associated methods.
     fn build_exception_class_related(&self, prim: PrimDef) -> TopLevelDef {
         // NOTE: currently only contains the class `Exception`
         debug_assert_prim_is_allowed(prim, [PrimDef::Exception]);
@@ -598,6 +604,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the class `Option`, its associated methods and the function `Some()`.
     fn build_option_class_related(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -716,6 +723,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the class `ndarray` and its associated methods.
     fn build_ndarray_class_related(&self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -776,6 +784,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build functions that cast a numeric primitive to another numeric primitive, including booleans.
     fn build_cast_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -826,6 +835,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the functions `round()` and `round64()`.
     fn build_round_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunRound, PrimDef::FunRound64]);
 
@@ -877,6 +887,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build the functions `ceil()` and `floor()`.
     fn build_ceil_floor_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -946,6 +957,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build ndarray factory functions that only take in an argument `shape` of type `list[int32]` and return an ndarray.
     fn build_ndarray_from_shape_factory_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -972,6 +984,9 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build ndarray factory functions that do not fit in any other `build_ndarray_*_factory_function` categories in [`BuiltinBuilder`].
+    ///
+    /// See also [`BuiltinBuilder::build_ndarray_from_shape_factory_function`].
     fn build_ndarray_other_factory_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -1084,6 +1099,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the `range()` function.
     fn build_range_function(&mut self) -> TopLevelDef {
         let prim = PrimDef::FunRange;
 
@@ -1208,6 +1224,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the `str()` function.
     fn build_str_function(&mut self) -> TopLevelDef {
         let prim = PrimDef::FunStr;
 
@@ -1235,6 +1252,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build functions `np_ceil()` and `np_floor()`.
     fn build_np_ceil_floor_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunNpCeil, PrimDef::FunNpFloor]);
 
@@ -1258,6 +1276,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build the `np_round()` function.
     fn build_np_round_function(&mut self) -> TopLevelDef {
         let prim = PrimDef::FunNpRound;
 
@@ -1275,6 +1294,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build the `len()` function.
     fn build_len_function(&mut self) -> TopLevelDef {
         let prim = PrimDef::FunLen;
 
@@ -1390,6 +1410,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the functions `min()` and `max()`.
     fn build_min_max_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunMin, PrimDef::FunMax]);
 
@@ -1427,6 +1448,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the functions `np_min()` and `np_max()`.
     fn build_np_min_max_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunNpMin, PrimDef::FunNpMax]);
 
@@ -1459,6 +1481,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
+    /// Build the functions `np_minimum()` and `np_maximum()`.
     fn build_np_minimum_maximum_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunNpMinimum, PrimDef::FunNpMaximum]);
 
@@ -1504,6 +1527,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
+    /// Build the `abs()` function.
     fn build_abs_function(&mut self) -> TopLevelDef {
         let prim = PrimDef::FunAbs;
 
@@ -1535,7 +1559,7 @@ impl<'a> BuiltinBuilder<'a> {
         }
     }
 
-    /// Build a numpy function that takes in a single float to returns a boolean
+    /// Build numpy functions that take in a float and return a boolean.
     fn build_np_float_to_bool_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(prim, [PrimDef::FunNpIsInf, PrimDef::FunNpIsNan]);
 
@@ -1562,7 +1586,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
-    /// Build a 1-ary numpy/scipy function that takes in a float or an ndarray and returns a value of the same type
+    /// Build 1-ary numpy/scipy functions that take in a float or an ndarray and return a value of the same type as the input.
     fn build_np_sp_float_or_ndarray_1ary_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -1662,7 +1686,7 @@ impl<'a> BuiltinBuilder<'a> {
         )
     }
 
-    /// Build a 2-ary numpy function
+    /// Build 2-ary numpy functions. The exact argument types of the two input arguments can be controlled.
     fn build_np_2ary_function(&mut self, prim: PrimDef) -> TopLevelDef {
         debug_assert_prim_is_allowed(
             prim,
@@ -1679,6 +1703,7 @@ impl<'a> BuiltinBuilder<'a> {
 
         let PrimitiveStore { float, int32, .. } = *self.primitives;
 
+        // The argument types of the two input arguments are controlled here.
         let (x1_ty, x2_ty) = match prim {
             PrimDef::FunNpArctan2 => (float, float),
             PrimDef::FunNpCopysign => (float, float),