Doc comment fixes.

Documentation/config.ld

@@ -1,4 +1,4 @@
-file = {"../TombEngine/Scripting/Internal", "../Scripts"}
+file = {"../TombEngine/Scripting/Internal", "../Scripts/Engine"}
 new_type("mem", "Members", false)
 new_type("files", "Script Files", true)
 new_type("entityclass", "Entity classes", true)

Scripts/Engine/EventSequence.lua

@@ -73,7 +73,7 @@ EventSequence = {
 	-- @bool loop if true, the sequence will start again from its first timer once its final function has been called
 	-- @tparam ?table|bool timerFormat same as in Timer. This is mainly for debugging. __This will not work properly if another sequence or timer is showing a countdown.__
 	-- @param[opt] ... a variable number of pairs of arguments - a time in seconds, followed by the function (must be defined in the LevelFuncs table) to call once the time has elapsed, followed by another duration in seconds, another function name, etc. You can specify a function either by its name as a string, or by a table with the function name as the first member, followed by its arguments (see above example).
-	-- @return The inactive sequence.
+	-- @treturn EventSequence The inactive sequence.
 	Create = function(name, loop, timerFormat, ...)
 		local obj = {}
 		local mt = {}
@@ -135,7 +135,7 @@ EventSequence = {
 
 	--- Get an event sequence by its name.
 	-- @string name The label that was given to the sequence when it was created
-	-- @return The sequence
+	-- @treturn EventSequence The sequence
 	Get = function(name)
 		if LevelVars.Engine.EventSequence.sequences[name] then
 			local obj = {}
@@ -158,7 +158,7 @@ EventSequence = {
 
 	--- Get whether or not the sequence is paused
 	-- @function mySequence:IsPaused
-	-- @return true if the timer is paused, false if otherwise
+	-- @treturn bool true if the timer is paused, false if otherwise
 	IsPaused = function(t)
 		local thisES = LevelVars.Engine.EventSequence.sequences[t.name]
 		return Timer.Get(thisES.timers[thisES.currentTimer]):IsPaused()
@@ -180,7 +180,7 @@ EventSequence = {
 
 	--- Get whether or not the sequence is active
 	-- @function mySequence:IsActive
-	-- @return true if the sequence is active, false if otherwise
+	-- @treturn bool true if the sequence is active, false if otherwise
 	IsActive = function(t)
 		local thisES = LevelVars.Engine.EventSequence.sequences[t.name]
 		return Timer.Get(thisES.timers[thisES.currentTimer]):IsActive()

Scripts/Engine/Timer.lua

@@ -67,7 +67,7 @@ Timer = {
 	-- @tparam ?table|bool timerFormat If a table is given, the remaining time will be shown as a string, formatted according to the values in the table. If true, the remaining seconds, rounded up, will show at the bottom of the screen. If false, the remaining time will not be shown on screen. 
 	-- @func func The LevelFunc function to call when the time is up
 	-- @param[opt] ... a variable number of arguments with which the above function will be called
-	-- @return The timer in its paused state
+	-- @treturn Timer The timer in its paused state
 	--
 	Create = function(name, totalTime, loop, timerFormat, func, ...)
 		local obj = {}
@@ -101,7 +101,7 @@ Timer = {
 
 	--- Get a timer by its name.
 	-- @string name The label that was given to the timer when it was created
-	-- @return The timer
+	-- @treturn Timer The timer
 	Get = function(name)
 		if LevelVars.Engine.Timer.timers[name] then
 			local obj = {}
@@ -234,7 +234,7 @@ Timer = {
 
 	--- Get whether or not the timer is active
 	-- @function myTimer:IsActive
-	-- @return true if the timer is active, false if otherwise
+	-- @treturn bool true if the timer is active, false if otherwise
 	IsActive = function(t)
 		return LevelVars.Engine.Timer.timers[t.name].active
 	end;
@@ -256,14 +256,14 @@ Timer = {
 
 	--- Get whether or not the timer is paused
 	-- @function myTimer:IsPaused
-	-- @return true if the timer is paused, false if otherwise
+	-- @treturn bool true if the timer is paused, false if otherwise
 	IsPaused = function(t)
 		return LevelVars.Engine.Timer.timers[t.name].paused
 	end;
 
 	--- Get the remaining time for a timer.
 	-- @function myTimer:GetRemainingTime
-	-- @return the time in seconds remaining on the clock
+	-- @treturn float the time in seconds remaining on the clock
 	GetRemainingTime = function(t)
 		return LevelVars.Engine.Timer.timers[t.name].remainingTime
 	end;
@@ -278,7 +278,7 @@ Timer = {
 	--- Get the total time for a timer.
 	-- This is the amount of time the timer will start with, as well as when starting a new loop
 	-- @function myTimer:GetRemainingTime
-	-- @return the timer's total time
+	-- @treturn float the timer's total time
 	GetTotalTime = function(t)
 		return LevelVars.Engine.Timer.timers[t.name].totalTime
 	end;

TombEngine/Scripting/Internal/TEN/Color/Color.cpp

@@ -40,7 +40,7 @@ void ScriptColor::Register(sol::table & parent)
 @int R red component
 @int G green component
 @int B blue component
-@return A Color object.
+@treturn Color A new Color object.
 @function Color
 */
 ScriptColor::ScriptColor(byte r, byte g, byte b) :
@@ -53,7 +53,7 @@ m_color(r, g, b)
 @int G green component
 @int B blue component
 @int A alpha component (255 is opaque, 0 is invisible)
-@return A Color object.
+@treturn Color A new Color object.
 @function Color
 */
 ScriptColor::ScriptColor(byte r, byte g, byte b, byte a) : ScriptColor(r, g, b)

TombEngine/Scripting/Internal/TEN/Flow/Fog/Fog.cpp

@@ -39,7 +39,7 @@ void Fog::Register(sol::table & parent)
 @tparam Color color RGB color
 @tparam int Min Distance fog starts (in Sectors)
 @tparam int Max Distance fog ends (in Sectors)
-@return A fog object.
+@treturn Fog A fog object.
 @function Fog
 */
 Fog::Fog(ScriptColor const& col, short minDistance, short maxDistance)

TombEngine/Scripting/Internal/TEN/Flow/InventoryItem/InventoryItem.cpp

@@ -33,7 +33,7 @@ Must be one of:
 	USE
 	EXAMINE
 e.g. `myItem.action = ItemAction.EXAMINE`
-	@return an InventoryItem
+	@treturn InventoryItem an InventoryItem
 */
 InventoryItem::InventoryItem(std::string const& a_name, GAME_OBJECT_ID a_slot, short a_yOffset, float a_scale, Rotation const & a_rot, RotationFlags a_rotationFlags, int a_meshBits, ItemOptions a_action) :
 	name{ a_name },

TombEngine/Scripting/Internal/TEN/Flow/Level/FlowLevel.cpp

@@ -12,7 +12,7 @@ These are things things which aren't present in the compiled level file itself.
 
 /*** Make a new Level object.
 	@function Level
-	@return a Level object
+	@treturn Level a Level object
 	*/
 void Level::Register(sol::table & parent)
 {	

TombEngine/Scripting/Internal/TEN/Flow/SkyLayer/SkyLayer.cpp

@@ -36,7 +36,7 @@ Less is more. City of The Dead, for example, uses a speed value of 16.
 /*** 
 @tparam Color color RGB color
 @tparam int speed cloud speed
-@return A SkyLayer object.
+@treturn SkyLayer A SkyLayer object.
 @function SkyLayer
 */
 SkyLayer::SkyLayer(ScriptColor const& col, short speed)

TombEngine/Scripting/Internal/TEN/Objects/Lara/LaraObject.cpp

@@ -170,11 +170,12 @@ void LaraObject::ThrowAwayTorch()
 }
 
 //todo make these into enums - Squidshire 18/11/2022
+
 /// Get actual hand status of Lara
 // @function LaraObject:GetHandStatus
 // @usage
 // local handStatus = Lara:GetHandStatus()
-// @treturn 0=HandsFree, 1=Busy(climbing,etc), 2=WeaponDraw, 3=WeaponUndraw, 4=WeaponInHand.
+// @treturn int hand status 0=HandsFree, 1=Busy(climbing,etc), 2=WeaponDraw, 3=WeaponUndraw, 4=WeaponInHand.
 HandStatus LaraObject::GetHandStatus() const
 {
 	auto* lara = GetLaraInfo(m_item);
@@ -182,11 +183,12 @@ HandStatus LaraObject::GetHandStatus() const
 }
 
 //todo make these into enums - Squidshire 18/11/2022
+
 /// Get actual weapon type of Lara
 // @function LaraObject:GetWeaponType
 // @usage
 // local weaponType = Lara:GetWeaponType()
-// @treturn 0=None, 1=Pistols, 2=Revolver, 3=Uzi, 4=Shotgun, 5=HK, 6=Crossbow, 7=Flare, 8=Torch, 9=GrenadeLauncher, 10=Harpoon, 11=RocketLauncher.
+// @treturn int weapon type 0=None, 1=Pistols, 2=Revolver, 3=Uzi, 4=Shotgun, 5=HK, 6=Crossbow, 7=Flare, 8=Torch, 9=GrenadeLauncher, 10=Harpoon, 11=RocketLauncher.
 LaraWeaponType LaraObject::GetWeaponType() const
 {
 	auto* lara = GetLaraInfo(m_item);

TombEngine/Scripting/Internal/TEN/Objects/Moveable/MoveableObject.cpp

@@ -84,7 +84,7 @@ most can just be ignored (see usage).
 	@int[opt=10] hp HP of item
 	@int[opt=0] OCB ocb of item (default 0)
 	@tparam[opt] table AIBits table with AI bits (default {0,0,0,0,0,0})
-	@return reference to new Moveable object
+	@treturn Moveable A new Moveable object (a wrapper around the new object)
 	@usage 
 	local item = Moveable(
 		TEN.Objects.ObjID.PISTOLS_ITEM, -- object id

TombEngine/Scripting/Internal/TEN/Rotation/Rotation.cpp

@@ -38,7 +38,7 @@ void Rotation::Register(sol::table & parent)
 @int X rotation about x axis
 @int Y rotation about y axis
 @int Z rotation about z axis
-@return A Rotation object.
+@treturn Rotation A Rotation object.
 @function Rotation
 */
 Rotation::Rotation(int aX, int aY, int aZ)

TombEngine/Scripting/Internal/TEN/Strings/DisplayString/DisplayString.cpp

@@ -51,7 +51,7 @@ strings.lua. __Default: false__.
 	TEN.Strings.DisplayStringOption.CENTER -- see x and y parameters
 	TEN.Strings.DisplayStringOption.SHADOW -- will give the text a small shadow
 __Default: empty__
-@return A new DisplayString object.
+@treturn DisplayString A new DisplayString object.
 */
 static std::unique_ptr<DisplayString> CreateString(std::string const & key, int x, int y, ScriptColor col, TypeOrNil<bool> maybeTranslated, TypeOrNil<sol::table> flags)
 {

TombEngine/Scripting/Internal/TEN/Vec3/Vec3.cpp

@@ -52,7 +52,7 @@ However, this function would return it as (0, 1, 1).
 @int X x coordinate
 @int Y y coordinate
 @int Z z coordinate
-@return A Vec3 object.
+@treturn Vec3 A Vec3 object.
 @function Vec3
 */
 Vec3::Vec3(int aX, int aY, int aZ) : x{aX}, y{aY}, z{aZ}