Add more documentation on why to use out-param

crates/luaffi_impl/src/metatype.rs

@@ -157,7 +157,18 @@ fn get_ffi_functions(imp: &mut ItemImpl) -> Result<Vec<FfiFunction>> {
                 ReturnType::Type(_, ref ty) => (**ty).clone(),
             };
 
-            // whether to use out-param for return values
+            // whether to use out-param for return values.
+            //
+            // out-param return convention isn't strictly necessary (luajit can handle them fine),
+            // but luajit doesn't jit compile aggregate returns yet, so this is more of a
+            // performance optimisation. https://luajit.org/ext_ffi_semantics.html#status
+            //
+            // right now this just heuristically looks for common primitive identifiers like `i32`
+            // and `usize` which has its limitations when it comes to type aliases (proc-macro can't
+            // see them), but the worst thing that can happen with a false detection is an
+            // unnecessarily boxed primitive that gets just unwrapped, or an aggregate suboptimally
+            // returned by-value. it should be correct for 99% of rust code that isn't doing
+            // anything weird.
             let ret_by_out = !is_primitive(&ret);
 
             funcs.push(FfiFunction {