From 7d0b184fa5a880500b66870b2601ca31e6d35bc5 Mon Sep 17 00:00:00 2001
From: John S <138552829+Multi-Volt@users.noreply.github.com>
Date: Thu, 12 Dec 2024 00:02:07 -0500
Subject: [PATCH] Document surface_collision.h (#549)

* Document surface_collision.h

Add documentation to the functions of surface_collision.h

* Make descriptions a little more clear

* Fix random space
---
 autogen/lua_definitions/functions.lua |  5 +++++
 docs/lua/functions-6.md               | 15 +++++++++++++++
 src/engine/surface_collision.h        | 25 +++++++++++++++++++++++++
 3 files changed, 45 insertions(+)

diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index 67a1e2171..f78eb3491 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -10094,6 +10094,7 @@ end
 --- @param y number
 --- @param z number
 --- @return number
+--- Finds the height of the highest ceiling above a given position (x, y, z). If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default)
 function find_ceil_height(x, y, z)
     -- ...
 end
@@ -10102,6 +10103,7 @@ end
 --- @param y number
 --- @param z number
 --- @return number
+--- Finds the height of the highest floor below a given position (x, y, z). If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default)
 function find_floor_height(x, y, z)
     -- ...
 end
@@ -10109,12 +10111,14 @@ end
 --- @param x number
 --- @param z number
 --- @return number
+--- Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
 function find_poison_gas_level(x, z)
     -- ...
 end
 
 --- @param colData WallCollisionData
 --- @return integer
+--- Detects wall collisions at a given position and adjusts the position based on the walls found. Returns the number of wall collisions detected.
 function find_wall_collisions(colData)
     -- ...
 end
@@ -10122,6 +10126,7 @@ end
 --- @param x number
 --- @param z number
 --- @return number
+--- Finds the height of water at a given position (x, z), if the position is within a water region. If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
 function find_water_level(x, z)
     -- ...
 end
diff --git a/docs/lua/functions-6.md b/docs/lua/functions-6.md
index 3cfaeed12..3b51ddb65 100644
--- a/docs/lua/functions-6.md
+++ b/docs/lua/functions-6.md
@@ -3397,6 +3397,9 @@ Replaces the secret star course name of `courseNum` with `courseName`
 
 ## [find_ceil_height](#find_ceil_height)
 
+### Description
+Finds the height of the highest ceiling above a given position (x, y, z). If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default)
+
 ### Lua Example
 `local numberValue = find_ceil_height(x, y, z)`
 
@@ -3419,6 +3422,9 @@ Replaces the secret star course name of `courseNum` with `courseName`
 
 ## [find_floor_height](#find_floor_height)
 
+### Description
+Finds the height of the highest floor below a given position (x, y, z). If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default)
+
 ### Lua Example
 `local numberValue = find_floor_height(x, y, z)`
 
@@ -3441,6 +3447,9 @@ Replaces the secret star course name of `courseNum` with `courseName`
 
 ## [find_poison_gas_level](#find_poison_gas_level)
 
+### Description
+Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
+
 ### Lua Example
 `local numberValue = find_poison_gas_level(x, z)`
 
@@ -3462,6 +3471,9 @@ Replaces the secret star course name of `courseNum` with `courseName`
 
 ## [find_wall_collisions](#find_wall_collisions)
 
+### Description
+Detects wall collisions at a given position and adjusts the position based on the walls found. Returns the number of wall collisions detected.
+
 ### Lua Example
 `local integerValue = find_wall_collisions(colData)`
 
@@ -3482,6 +3494,9 @@ Replaces the secret star course name of `courseNum` with `courseName`
 
 ## [find_water_level](#find_water_level)
 
+### Description
+Finds the height of water at a given position (x, z), if the position is within a water region. If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
+
 ### Lua Example
 `local numberValue = find_water_level(x, z)`
 
diff --git a/src/engine/surface_collision.h b/src/engine/surface_collision.h
index cbf4353fb..a8eaf0820 100644
--- a/src/engine/surface_collision.h
+++ b/src/engine/surface_collision.h
@@ -43,13 +43,38 @@ extern u8 gFindWallDirectionActive;
 extern u8 gFindWallDirectionAirborne;
 
 s32 f32_find_wall_collision(f32 *xPtr, f32 *yPtr, f32 *zPtr, f32 offsetY, f32 radius);
+
+/* |description|
+Detects wall collisions at a given position and adjusts the position based on the walls found. 
+Returns the number of wall collisions detected.
+|descriptionEnd| */
 s32 find_wall_collisions(struct WallCollisionData *colData);
 f32 find_ceil(f32 posX, f32 posY, f32 posZ, struct Surface **pceil);
+
+/* |description|
+Finds the height of the highest ceiling above a given position (x, y, z). 
+If no ceiling is found, returns the default height limit of `gLevelValues.cellHeightLimit`(20000 by default)
+|descriptionEnd| */
 f32 find_ceil_height(f32 x, f32 y, f32 z);
 f32 find_floor_height_and_data(f32 xPos, f32 yPos, f32 zPos, struct FloorGeometry **floorGeo);
+
+/* |description|
+Finds the height of the highest floor below a given position (x, y, z). 
+If no floor is found, returns the default floor height of `gLevelValues.floorLowerLimit`(-11000 by default)
+|descriptionEnd| */
 f32 find_floor_height(f32 x, f32 y, f32 z);
 f32 find_floor(f32 xPos, f32 yPos, f32 zPos, struct Surface **pfloor);
+
+/* |description|
+Finds the height of water at a given position (x, z), if the position is within a water region. 
+If no water is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
+|descriptionEnd| */
 f32 find_water_level(f32 x, f32 z);
+
+/* |description|
+Finds the height of the poison gas at a given position (x, z), if the position is within a gas region. 
+If no gas is found, returns the default height of `gLevelValues.floorLowerLimit`(-11000 by default)
+|descriptionEnd| */
 f32 find_poison_gas_level(f32 x, f32 z);
 void debug_surface_list_info(f32 xPos, f32 zPos);
 void find_surface_on_ray(Vec3f orig, Vec3f dir, struct Surface **hit_surface, Vec3f hit_pos, f32 precision);