Clean up l_object.cpp (#10512)

Co-authored-by: Zughy <4279489-marco_a@users.noreply.gitlab.com>

doc/lua_api.txt

@@ -6217,18 +6217,18 @@ object you are working with still exists.
     * `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading)
       and Z is roll (bank).
 * `get_rotation()`: returns the rotation, a vector (radians)
-* `set_yaw(radians)`: sets the yaw (heading).
+* `set_yaw(yaw)`: sets the yaw in radians (heading).
 * `get_yaw()`: returns number in radians
 * `set_texture_mod(mod)`
     * Set a texture modifier to the base texture, for sprites and meshes.
     * When calling `set_texture_mod` again, the previous one is discarded.
     * `mod` the texture modifier. See [Texture modifiers].
 * `get_texture_mod()` returns current texture modifier
-* `set_sprite(p, num_frames, framelength, select_x_by_camera)`
+* `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)`
     * Specifies and starts a sprite animation
     * Animations iterate along the frame `y` position.
-    * `p`: {x=column number, y=row number}, the coordinate of the first frame
+    * `start_frame`: {x=column number, y=row number}, the coordinate of the
-      default: `{x=0, y=0}`
+      first frame, default: `{x=0, y=0}`
     * `num_frames`: Total frames in the texture, default: `1`
     * `framelength`: Time per animated frame in seconds, default: `0.2`
     * `select_x_by_camera`: Only for visual = `sprite`. Changes the frame `x`
@@ -6391,8 +6391,8 @@ object you are working with still exists.
           nodes square)
     * `selected_mode` is the mode index to be selected after modes have been changed
     (0 is the first mode).
-* `set_sky(parameters)`
+* `set_sky(sky_parameters)`
-    * `parameters` is a table with the following optional fields:
+    * `sky_parameters` is a table with the following optional fields:
         * `base_color`: ColorSpec, changes fog in "skybox" and "plain".
         * `type`: Available types:
             * `"regular"`: Uses 0 textures, `base_color` ignored
@@ -6436,8 +6436,8 @@ object you are working with still exists.
 * `get_sky()`: returns base_color, type, table of textures, clouds.
 * `get_sky_color()`: returns a table with the `sky_color` parameters as in
     `set_sky`.
-* `set_sun(parameters)`:
+* `set_sun(sun_parameters)`:
-    * `parameters` is a table with the following optional fields:
+    * `sun_parameters` is a table with the following optional fields:
         * `visible`: Boolean for whether the sun is visible.
             (default: `true`)
         * `texture`: A regular texture for the sun. Setting to `""`
@@ -6451,8 +6451,8 @@ object you are working with still exists.
         * `scale`: Float controlling the overall size of the sun. (default: `1`)
 * `get_sun()`: returns a table with the current sun parameters as in
     `set_sun`.
-* `set_moon(parameters)`:
+* `set_moon(moon_parameters)`:
-    * `parameters` is a table with the following optional fields:
+    * `moon_parameters` is a table with the following optional fields:
         * `visible`: Boolean for whether the moon is visible.
             (default: `true`)
         * `texture`: A regular texture for the moon. Setting to `""`
@@ -6462,8 +6462,8 @@ object you are working with still exists.
         * `scale`: Float controlling the overall size of the moon (default: `1`)
 * `get_moon()`: returns a table with the current moon parameters as in
     `set_moon`.
-* `set_stars(parameters)`:
+* `set_stars(star_parameters)`:
-    * `parameters` is a table with the following optional fields:
+    * `star_parameters` is a table with the following optional fields:
         * `visible`: Boolean for whether the stars are visible.
             (default: `true`)
         * `count`: Integer number to set the number of stars in
@@ -6475,8 +6475,8 @@ object you are working with still exists.
         * `scale`: Float controlling the overall size of the stars (default: `1`)
 * `get_stars()`: returns a table with the current stars parameters as in
     `set_stars`.
-* `set_clouds(parameters)`: set cloud parameters
+* `set_clouds(cloud_parameters)`: set cloud parameters
-    * `parameters` is a table with the following optional fields:
+    * `cloud_parameters` is a table with the following optional fields:
         * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
         * `color`: basic cloud color with alpha channel, ColorSpec
           (default `#fff0f0e5`).
@@ -6494,21 +6494,17 @@ object you are working with still exists.
       amount.
     * `nil`: Disables override, defaulting to sunlight based on day-night cycle
 * `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
-* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`:
+* `set_local_animation(idle, walk, dig, walk_while_dig, frame_speed)`:
-  set animation for player model in third person view
+  set animation for player model in third person view.
-
+    * Every animation equals to a `{x=starting frame, y=ending frame}` table.
-      set_local_animation({x=0, y=79},  -- stand/idle animation key frames
+    * `frame_speed` sets the animations frame speed. Default is 30.
-          {x=168, y=187},  -- walk animation key frames
+* `get_local_animation()`: returns idle, walk, dig, walk_while_dig tables and
-          {x=189, y=198},  -- dig animation key frames
-          {x=200, y=219},  -- walk+dig animation key frames
-          frame_speed=30)  -- animation frame speed
-* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and
   `frame_speed`.
-* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for
+* `set_eye_offset(firstperson, thirdperson)`: defines offset vectors for camera
-  camera per player.
+  per player.
     * in first person view
     * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
-* `get_eye_offset()`: returns `offset_first` and `offset_third`
+* `get_eye_offset()`: returns first and third person offsets.
 * `send_mapblock(blockpos)`:
     * Sends a server-side loaded mapblock to the player.
     * Returns `false` if failed.

src/script/lua_api/l_object.h

@@ -69,29 +69,24 @@ private:
 	static int l_remove(lua_State *L);
 
 	// get_pos(self)
-	// returns: {x=num, y=num, z=num}
 	static int l_get_pos(lua_State *L);
 
 	// set_pos(self, pos)
 	static int l_set_pos(lua_State *L);
 
-	// move_to(self, pos, continuous=false)
+	// move_to(self, pos, continuous)
 	static int l_move_to(lua_State *L);
 
 	// punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
 	static int l_punch(lua_State *L);
 
-	// right_click(self, clicker); clicker = an another ObjectRef
+	// right_click(self, clicker)
 	static int l_right_click(lua_State *L);
 
-	// set_hp(self, hp)
+	// set_hp(self, hp, reason)
-	// hp = number of hitpoints (2 * number of hearts)
-	// returns: nil
 	static int l_set_hp(lua_State *L);
 
 	// get_hp(self)
-	// returns: number of hitpoints (2 * number of hearts)
-	// 0 if not applicable to this type of object
 	static int l_get_hp(lua_State *L);
 
 	// get_inventory(self)
@@ -106,7 +101,7 @@ private:
 	// get_wielded_item(self)
 	static int l_get_wielded_item(lua_State *L);
 
-	// set_wielded_item(self, itemstack or itemstring or table or nil)
+	// set_wielded_item(self, item)
 	static int l_set_wielded_item(lua_State *L);
 
 	// set_armor_groups(self, groups)
@@ -115,8 +110,7 @@ private:
 	// get_armor_groups(self)
 	static int l_get_armor_groups(lua_State *L);
 
-	// set_physics_override(self, physics_override_speed, physics_override_jump,
+	// set_physics_override(self, override_table)
-	//                      physics_override_gravity, sneak, sneak_glitch, new_move)
 	static int l_set_physics_override(lua_State *L);
 
 	// get_physics_override(self)
@@ -131,7 +125,7 @@ private:
 	// get_animation(self)
 	static int l_get_animation(lua_State *L);
 
-	// set_bone_position(self, std::string bone, v3f position, v3f rotation)
+	// set_bone_position(self, bone, position, rotation)
 	static int l_set_bone_position(lua_State *L);
 
 	// get_bone_position(self, bone)
@@ -160,28 +154,28 @@ private:
 
 	/* LuaEntitySAO-only */
 
-	// set_velocity(self, {x=num, y=num, z=num})
+	// set_velocity(self, velocity)
 	static int l_set_velocity(lua_State *L);
 
-	// add_velocity(self, {x=num, y=num, z=num})
+	// add_velocity(self, velocity)
 	static int l_add_velocity(lua_State *L);
 
 	// get_velocity(self)
 	static int l_get_velocity(lua_State *L);
 
-	// set_acceleration(self, {x=num, y=num, z=num})
+	// set_acceleration(self, acceleration)
 	static int l_set_acceleration(lua_State *L);
 
 	// get_acceleration(self)
 	static int l_get_acceleration(lua_State *L);
 
-	// set_rotation(self, {x=num, y=num, z=num})
+	// set_rotation(self, rotation)
 	static int l_set_rotation(lua_State *L);
 
 	// get_rotation(self)
 	static int l_get_rotation(lua_State *L);
 
-	// set_yaw(self, radians)
+	// set_yaw(self, yaw)
 	static int l_set_yaw(lua_State *L);
 
 	// get_yaw(self)
@@ -193,8 +187,7 @@ private:
 	// l_get_texture_mod(self)
 	static int l_get_texture_mod(lua_State *L);
 
-	// set_sprite(self, p={x=0,y=0}, num_frames=1, framelength=0.2,
+	// set_sprite(self, start_frame, num_frames, framelength, select_x_by_camera)
-	//           select_horiz_by_yawpitch=false)
 	static int l_set_sprite(lua_State *L);
 
 	// DEPRECATED
@@ -206,9 +199,6 @@ private:
 
 	/* Player-only */
 
-	// is_player_connected(self)
-	static int l_is_player_connected(lua_State *L);
-
 	// get_player_name(self)
 	static int l_get_player_name(lua_State *L);
 
@@ -232,7 +222,7 @@ private:
 	// get_look_yaw2(self)
 	static int l_get_look_horizontal(lua_State *L);
 
-	// set_fov(self, degrees, is_multiplier)
+	// set_fov(self, degrees, is_multiplier, transition_time)
 	static int l_set_fov(lua_State *L);
 
 	// set_look_vertical(self, radians)
@@ -255,9 +245,11 @@ private:
 	// get_breath(self, breath)
 	static int l_get_breath(lua_State *L);
 
+	// DEPRECATED
 	// set_attribute(self, attribute, value)
 	static int l_set_attribute(lua_State *L);
 
+	// DEPRECATED
 	// get_attribute(self, attribute)
 	static int l_get_attribute(lua_State *L);
 
@@ -267,13 +259,13 @@ private:
 	// set_inventory_formspec(self, formspec)
 	static int l_set_inventory_formspec(lua_State *L);
 
-	// get_inventory_formspec(self) -> formspec
+	// get_inventory_formspec(self)
 	static int l_get_inventory_formspec(lua_State *L);
 
 	// set_formspec_prepend(self, formspec)
 	static int l_set_formspec_prepend(lua_State *L);
 
-	// get_formspec_prepend(self) -> formspec
+	// get_formspec_prepend(self)
 	static int l_get_formspec_prepend(lua_State *L);
 
 	// get_player_control(self)
@@ -321,7 +313,7 @@ private:
 	// hud_get_hotbar_selected_image(self)
 	static int l_hud_get_hotbar_selected_image(lua_State *L);
 
-	// set_sky({base_color=, type=, textures=, clouds=, sky_colors={}})
+	// set_sky(self, sky_parameters)
 	static int l_set_sky(lua_State *L);
 
 	// get_sky(self)
@@ -330,25 +322,25 @@ private:
 	// get_sky_color(self)
 	static int l_get_sky_color(lua_State* L);
 
-	// set_sun(self, {visible, texture=, tonemap=, sunrise=, rotation=, scale=})
+	// set_sun(self, sun_parameters)
 	static int l_set_sun(lua_State *L);
 
 	// get_sun(self)
 	static int l_get_sun(lua_State *L);
 
-	// set_moon(self, {visible, texture=, tonemap=, rotation, scale=})
+	// set_moon(self, moon_parameters)
 	static int l_set_moon(lua_State *L);
 
 	// get_moon(self)
 	static int l_get_moon(lua_State *L);
 
-	// set_stars(self, {visible, count=, starcolor=, rotation, scale=})
+	// set_stars(self, star_parameters)
 	static int l_set_stars(lua_State *L);
 
 	// get_stars(self)
 	static int l_get_stars(lua_State *L);
 
-	// set_clouds(self, {density=, color=, ambient=, height=, thickness=, speed=})
+	// set_clouds(self, cloud_parameters)
 	static int l_set_clouds(lua_State *L);
 
 	// get_clouds(self)
@@ -360,13 +352,13 @@ private:
 	// get_day_night_ratio(self)
 	static int l_get_day_night_ratio(lua_State *L);
 
-	// set_local_animation(self, {stand/idle}, {walk}, {dig}, {walk+dig}, frame_speed)
+	// set_local_animation(self, idle, walk, dig, walk_while_dig, frame_speed)
 	static int l_set_local_animation(lua_State *L);
 
 	// get_local_animation(self)
 	static int l_get_local_animation(lua_State *L);
 
-	// set_eye_offset(self, v3f first pv, v3f third pv)
+	// set_eye_offset(self, firstperson, thirdperson)
 	static int l_set_eye_offset(lua_State *L);
 
 	// get_eye_offset(self)