Document is_complex and is_memory_allocated type attributes (#1444)

* Document is_complex

* Document is_memory_allocated

* Add rationale for is_memory_allocated

Author: JulianGCalderon

src/executor.rs

@@ -109,13 +109,17 @@ fn invoke_dynamic(
         .peekable();
 
     let num_return_args = ret_types_iter.clone().count();
+    // If there is more than one return value, or the return value is _complex_,
+    // as defined by the architecture ABI, then we pass a return pointer as
+    // the first argument to the program entrypoint.
     let mut return_ptr = if num_return_args > 1
         || ret_types_iter
             .peek()
             .map(|id| registry.get_type(id)?.is_complex(registry))
             .transpose()?
             == Some(true)
     {
+        // The return pointer should be able to hold all the return values.
         let layout = ret_types_iter.try_fold(Layout::new::<()>(), |layout, id| {
             let type_info = registry.get_type(id)?;
             Result::<_, Error>::Ok(layout.extend(type_info.layout(registry)?)?.0)

src/types.rs

@@ -85,11 +85,26 @@ pub trait TypeBuilder {
 
     /// Return whether the type is a builtin.
     fn is_builtin(&self) -> bool;
-    /// Return whether the type requires a return pointer when returning.
+    /// Return whether the type requires a return pointer when returning,
+    /// instead of using the CPU registers.
+    ///
+    /// This attribute does not modify the compilation, and it only reflects
+    /// what the ABI of the target architecture already specifies.
+    /// - For x86-64: https://gitlab.com/x86-psABIs/x86-64-ABI.
+    /// - For AArch64: https://github.com/ARM-software/abi-aa.
+    ///
+    /// We can validate this empirically, by building a Cairo program that
+    /// returns a particular type, and seeing how it is lowered to machine code.
+    ///
+    /// ```bash
+    /// llc a.llvmir -o - --mtriple "aarch64"
+    /// llc a.llvmir -o - --mtriple "x86_64"
+    /// ```
     fn is_complex(
         &self,
         registry: &ProgramRegistry<CoreType, CoreLibfunc>,
     ) -> Result<bool, Self::Error>;
+
     /// Return whether the Sierra type resolves to a zero-sized type.
     fn is_zst(
         &self,
@@ -104,8 +119,21 @@ pub trait TypeBuilder {
         registry: &ProgramRegistry<CoreType, CoreLibfunc>,
     ) -> Result<Layout, Self::Error>;
 
-    /// Whether the layout should be allocated in memory (either the stack or the heap) when used as
-    /// a function invocation argument or return value.
+    /// Whether the layout should be allocated in memory (either the stack or
+    /// the heap) when used as a function invocation argument or return value.
+    ///
+    /// Unlike `is_complex`, this attribute alters the compilation:
+    ///
+    /// - When passing a memory allocated value to a function, we allocate that
+    ///   value on the stack, and pass a pointer to it.
+    ///
+    /// - If a function returns a memory allocated value, we receive a return
+    ///   pointer as its first argument, and write the return value there
+    ///   instead.
+    ///
+    /// The rationale behind allocating a value in memory, rather than
+    /// registers, is to avoid putting too much pressure on the register
+    /// allocation pass for really complex types, like enums.
     fn is_memory_allocated(
         &self,
         registry: &ProgramRegistry<CoreType, CoreLibfunc>,