From d94cf00eb9db455e8d5bed73267865877d37965a Mon Sep 17 00:00:00 2001
From: PeachyPeach <72323920+PeachyPeachSM64@users.noreply.github.com>
Date: Fri, 2 May 2025 16:34:43 +0200
Subject: [PATCH] Fix wrongly documented functions (#783)

---
 autogen/lua_definitions/functions.lua |  8 ++---
 docs/lua/functions-5.md               |  8 ++---
 src/game/object_helpers.c             | 45 +++++++++++++--------------
 3 files changed, 30 insertions(+), 31 deletions(-)

diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index 01080d0a4..9816c795a 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -7819,7 +7819,7 @@ end
 --- @param m Mat4
 --- @param dst Vec3f
 --- @param v Vec3f
---- Overrides the current room Mario is in. Set to -1 to reset override
+--- Multiplies a vector by a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space
 function linear_mtxf_mul_vec3f(m, dst, v)
     -- ...
 end
@@ -7827,7 +7827,7 @@ end
 --- @param m Mat4
 --- @param dst Vec3f
 --- @param v Vec3f
---- Overrides the current room Mario is in. Set to -1 to reset override
+--- Multiplies a vector by the transpose of a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space
 function linear_mtxf_transpose_mul_vec3f(m, dst, v)
     -- ...
 end
@@ -8118,7 +8118,7 @@ function cur_obj_clear_interact_status_flag(flag)
 end
 
 --- @param obj Object
---- Overrides the current room Mario is in. Set to -1 to reset override
+--- Marks an object to be unloaded at the end of the frame
 function obj_mark_for_deletion(obj)
     -- ...
 end
@@ -8458,7 +8458,7 @@ end
 --- @param obj Object
 --- @param posIndex integer
 --- @param localTranslateIndex integer
---- Overrides the current room Mario is in. Set to -1 to reset override
+--- Transforms the vector at `localTranslateIndex` into the object's local coordinates, and then adds it to the vector at `posIndex`
 function obj_translate_local(obj, posIndex, localTranslateIndex)
     -- ...
 end
diff --git a/docs/lua/functions-5.md b/docs/lua/functions-5.md
index 3f3c7d4f7..230b91c49 100644
--- a/docs/lua/functions-5.md
+++ b/docs/lua/functions-5.md
@@ -2748,7 +2748,7 @@ Overrides the current room Mario is in. Set to -1 to reset override
 ## [linear_mtxf_mul_vec3f](#linear_mtxf_mul_vec3f)
 
 ### Description
-Overrides the current room Mario is in. Set to -1 to reset override
+Multiplies a vector by a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space
 
 ### Lua Example
 `linear_mtxf_mul_vec3f(m, dst, v)`
@@ -2773,7 +2773,7 @@ Overrides the current room Mario is in. Set to -1 to reset override
 ## [linear_mtxf_transpose_mul_vec3f](#linear_mtxf_transpose_mul_vec3f)
 
 ### Description
-Overrides the current room Mario is in. Set to -1 to reset override
+Multiplies a vector by the transpose of a matrix of the form: `| ? ? ? 0 |` `| ? ? ? 0 |` `| ? ? ? 0 |` `| 0 0 0 1 |` i.e. a matrix representing a linear transformation over 3 space
 
 ### Lua Example
 `linear_mtxf_transpose_mul_vec3f(m, dst, v)`
@@ -3814,7 +3814,7 @@ Overrides the current room Mario is in. Set to -1 to reset override
 ## [obj_mark_for_deletion](#obj_mark_for_deletion)
 
 ### Description
-Overrides the current room Mario is in. Set to -1 to reset override
+Marks an object to be unloaded at the end of the frame
 
 ### Lua Example
 `obj_mark_for_deletion(obj)`
@@ -5012,7 +5012,7 @@ Overrides the current room Mario is in. Set to -1 to reset override
 ## [obj_translate_local](#obj_translate_local)
 
 ### Description
-Overrides the current room Mario is in. Set to -1 to reset override
+Transforms the vector at `localTranslateIndex` into the object's local coordinates, and then adds it to the vector at `posIndex`
 
 ### Lua Example
 `obj_translate_local(obj, posIndex, localTranslateIndex)`
diff --git a/src/game/object_helpers.c b/src/game/object_helpers.c
index 5b8a63064..944f6f1dd 100644
--- a/src/game/object_helpers.c
+++ b/src/game/object_helpers.c
@@ -816,14 +816,14 @@ void obj_init_animation(struct Object *obj, s32 animIndex) {
     }
 }
 
-/**
- * Multiply a vector by a matrix of the form
- * | ? ? ? 0 |
- * | ? ? ? 0 |
- * | ? ? ? 0 |
- * | 0 0 0 1 |
- * i.e. a matrix representing a linear transformation over 3 space.
- */
+/* |description|
+Multiplies a vector by a matrix of the form:
+`| ? ? ? 0 |`
+`| ? ? ? 0 |`
+`| ? ? ? 0 |`
+`| 0 0 0 1 |`
+i.e. a matrix representing a linear transformation over 3 space
+|descriptionEnd| */
 void linear_mtxf_mul_vec3f(Mat4 m, Vec3f dst, Vec3f v) {
     s32 i;
     for (i = 0; i < 3; i++) {
@@ -831,14 +831,14 @@ void linear_mtxf_mul_vec3f(Mat4 m, Vec3f dst, Vec3f v) {
     }
 }
 
-/**
- * Multiply a vector by the transpose of a matrix of the form
- * | ? ? ? 0 |
- * | ? ? ? 0 |
- * | ? ? ? 0 |
- * | 0 0 0 1 |
- * i.e. a matrix representing a linear transformation over 3 space.
- */
+/* |description|
+Multiplies a vector by the transpose of a matrix of the form:
+`| ? ? ? 0 |`
+`| ? ? ? 0 |`
+`| ? ? ? 0 |`
+`| 0 0 0 1 |`
+i.e. a matrix representing a linear transformation over 3 space
+|descriptionEnd| */
 void linear_mtxf_transpose_mul_vec3f(Mat4 m, Vec3f dst, Vec3f v) {
     s32 i;
     for (i = 0; i < 3; i++) {
@@ -1469,9 +1469,9 @@ s32 cur_obj_clear_interact_status_flag(s32 flag) {
     return FALSE;
 }
 
-/**
- * Mark an object to be unloaded at the end of the frame.
- */
+/* |description|
+Marks an object to be unloaded at the end of the frame
+|descriptionEnd| */
 void obj_mark_for_deletion(struct Object *obj) {
     //! This clears all activeFlags. Since some of these flags disable behavior,
     //  setting it to 0 could potentially enable unexpected behavior. After an
@@ -2314,10 +2314,9 @@ void obj_set_gfx_pos_at_obj_pos(struct Object *obj1, struct Object *obj2) {
     obj1->header.gfx.angle[2] = obj2->oMoveAngleRoll & 0xFFFF;
 }
 
-/**
- * Transform the vector at localTranslateIndex into the object's local
- * coordinates, and then add it to the vector at posIndex.
- */
+/* |description|
+Transforms the vector at `localTranslateIndex` into the object's local coordinates, and then adds it to the vector at `posIndex`
+|descriptionEnd| */
 void obj_translate_local(struct Object *obj, s16 posIndex, s16 localTranslateIndex) {
     if (obj == NULL) { return; }
     f32 dx = obj->rawData.asF32[localTranslateIndex + 0];