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

@@ -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

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)`
 

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);