Add Object method documentation and drop Object:UpdateUInt32.

UpdateUInt32 appears to be a deprecated method and isn't used anywhere
else in CMaNGOS. SetUInt32 should be used instead.

LuaFunctions.cpp

@@ -151,7 +151,6 @@ ElunaRegister<Object> ObjectMethods[] =
     // Setters
     { "SetInt32Value", &LuaObject::SetInt32Value },           // :SetInt32Value(index, value) - Sets an int value for the object
     { "SetUInt32Value", &LuaObject::SetUInt32Value },         // :SetUInt32Value(index, value) - Sets an uint value for the object
-    { "UpdateUInt32Value", &LuaObject::UpdateUInt32Value },   // :UpdateUInt32Value(index, value) - Updates an uint value for the object
     { "SetFloatValue", &LuaObject::SetFloatValue },           // :SetFloatValue(index, value) - Sets a float value for the object
     { "SetByteValue", &LuaObject::SetByteValue },             // :SetByteValue(index, offset, value) - Sets a byte value for the object
     { "SetUInt16Value", &LuaObject::SetUInt16Value },         // :SetUInt16Value(index, offset, value) - Sets an uint16 value for the object

ObjectMethods.h

@@ -7,9 +7,29 @@
 #ifndef OBJECTMETHODS_H
 #define OBJECTMETHODS_H
 
+/***
+ * A basic game object (either an [Item] or a [WorldObject]).
+ *
+ * Objects in MaNGOS/Trinity are stored an a giant block of "values".
+ * Subclasses of Object, like [WorldObject], extend the block with more data specific to that subclass.
+ * Further subclasses, like [Player], extend it even further.
+ *
+ * A detailed map of all the fields in this data block can be found in the UpdateFields.h file of your emulator
+ *   (it varies depending on the expansion supported).
+ *
+ * The GetValue methods in this class (e.g. [Object:GetInt32Value]) provide low-level access to the data block.
+ * Other methods, like [Object:HasFlag] and [Object:GetScale], merely wrap the GetValue methods and provide a simpler interface.
+ */
 namespace LuaObject
 {
     /* BOOLEAN */
+    /**
+     * Returns `true` if the specified flag is set, otherwise `false`.
+     *
+     * @param uint16 index : the index of the flags data in the [Object]
+     * @param uint32 flag : the flag to check for in the flags data
+     * @return bool hasFlag
+     */
     int HasFlag(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -19,6 +39,11 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns `true` if the [Object] has been added to its [Map], otherwise `false`.
+     *
+     * @return bool inWorld
+     */
     int IsInWorld(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->IsInWorld());
@@ -26,6 +51,12 @@ namespace LuaObject
     }
 
     /* GETTERS */
+    /**
+     * Returns the data at the specified index, casted to a signed 32-bit integer.
+     *
+     * @param uint16 index
+     * @return int32 value
+     */
     int GetInt32Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -33,6 +64,12 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns the data at the specified index, casted to a unsigned 32-bit integer.
+     *
+     * @param uint16 index
+     * @return uint32 value
+     */
     int GetUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -40,6 +77,12 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns the data at the specified index, casted to a single-precision floating point value.
+     *
+     * @param uint16 index
+     * @return float value
+     */
     int GetFloatValue(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -47,6 +90,15 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns the data at the specified index and offset, casted to an unsigned 8-bit integer.
+     *
+     * E.g. if you want the second byte at index 10, you would pass in 1 as the offset.
+     *
+     * @param uint16 index
+     * @param uint8 offset : should be 0, 1, 2, or 3
+     * @return uint8 value
+     */
     int GetByteValue(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -55,6 +107,15 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns the data at the specified index and offset, casted to a signed 16-bit integer.
+     *
+     * E.g. if you want the second half-word at index 10, you would pass in 1 as the offset.
+     *
+     * @param uint16 index
+     * @param uint8 offset : should be 0 or 1
+     * @return uint16 value
+     */
     int GetUInt16Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -63,36 +124,86 @@ namespace LuaObject
         return 1;
     }
 
+    /**
+     * Returns the scale/size of the [Object].
+     *
+     * This affects the size of a [WorldObject] in-game, but [Item]s don't have a "scale".
+     *
+     * @return float scale
+     */
     int GetScale(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->GetObjectScale());
         return 1;
     }
 
+    /**
+     * Returns the entry of the [Object].
+     *
+     * [Player]s do not have an "entry".
+     *
+     * @return uint32 entry
+     */
     int GetEntry(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->GetEntry());
         return 1;
     }
 
+    /**
+     * Returns the GUID of the [Object].
+     *
+     * @return uint64 guid
+     */
     int GetGUID(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->GET_GUID());
         return 1;
     }
 
+    /**
+     * Returns the low-part of the [Object]'s GUID.
+     *
+     * This is the counter that is unique among [Object]s of the same type
+     *   (e.g. no two [Creature]s will have a low-GUID of 5 at the same time).
+     *
+     * @return uint32 guidLow
+     */
     int GetGUIDLow(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->GetGUIDLow());
         return 1;
     }
 
+    /**
+     * Returns the TypeId of the [Object].
+     *
+     *     enum TypeID
+     *     {
+     *         TYPEID_OBJECT        = 0,
+     *         TYPEID_ITEM          = 1,
+     *         TYPEID_CONTAINER     = 2,
+     *         TYPEID_UNIT          = 3,
+     *         TYPEID_PLAYER        = 4,
+     *         TYPEID_GAMEOBJECT    = 5,
+     *         TYPEID_DYNAMICOBJECT = 6,
+     *         TYPEID_CORPSE        = 7
+     *     };
+     *
+     * @return uint8 typeID
+     */
     int GetTypeId(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->GetTypeId());
         return 1;
     }
 
+    /**
+     * Returns the data at the specified index, casted to an unsigned 64-bit integer.
+     *
+     * @param uint16 index
+     * @return uint64 value
+     */
     int GetUInt64Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -101,6 +212,16 @@ namespace LuaObject
     }
 
     /* SETTERS */
+    /**
+     * Sets the specified flag in the data value at the specified index.
+     *
+     * If the flag was already set, it remains set.
+     *
+     * To remove a flag, use [Object:RemoveFlag].
+     *
+     * @param uint16 index
+     * @param uint32 value
+     */
     int SetFlag(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -110,6 +231,12 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to a signed 32-bit integer.
+     *
+     * @param uint16 index
+     * @param int32 value
+     */
     int SetInt32Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -118,6 +245,12 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to an unsigned 32-bit integer.
+     *
+     * @param uint16 index
+     * @param uint32 value
+     */
     int SetUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -126,6 +259,12 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to a single-precision floating point value.
+     *
+     * @param uint16 index
+     * @param float value
+     */
     int SetFloatValue(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -135,6 +274,13 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index and offset to the given value, converted to an unsigned 8-bit integer.
+     *
+     * @param uint16 index
+     * @param uint8 offset : should be 0, 1, 2, or 3
+     * @param uint8 value
+     */
     int SetByteValue(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -144,6 +290,13 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to an unsigned 16-bit integer.
+     *
+     * @param uint16 index
+     * @param uint8 offset : should be 0 or 1
+     * @param uint16 value
+     */
     int SetUInt16Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -153,6 +306,13 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to a signed 16-bit integer.
+     *
+     * @param uint16 index
+     * @param uint8 offset : should be 0 or 1
+     * @param int16 value
+     */
     int SetInt16Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -162,6 +322,11 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the [Object]'s scale/size to the given value.
+     *
+     * @param float scale
+     */
     int SetScale(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         float size = Eluna::CHECKVAL<float>(L, 2);
@@ -170,6 +335,12 @@ namespace LuaObject
         return 0;
     }
 
+    /**
+     * Sets the data at the specified index to the given value, converted to an unsigned 64-bit integer.
+     *
+     * @param uint16 index
+     * @param uint64 value
+     */
     int SetUInt64Value(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -179,6 +350,12 @@ namespace LuaObject
     }
 
     /* OTHER */
+    /**
+     * Removes a flag from the value at the specified index.
+     *
+     * @param uint16 index
+     * @param uint32 flag
+     */
     int RemoveFlag(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
@@ -188,38 +365,65 @@ namespace LuaObject
         return 0;
     }
 
-    int UpdateUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj)
+    /**
-    {
+     * Attempts to convert the [Object] to a [Corpse].
-        uint16 index = Eluna::CHECKVAL<uint16>(L, 2);
+     *
-        uint32 value = Eluna::CHECKVAL<uint32>(L, 3);
+     * If the [Object] is not a [Corpse], returns `nil`.
-        obj->UpdateUInt32Value(index, value);
+     *
-        return 0;
+     * @return [Corpse] corpse : the [Object] as a [Corpse], or `nil`
-    }
+     */
-
     int ToCorpse(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->ToCorpse());
         return 1;
     }
 
+    /**
+     * Attempts to convert the [Object] to a [GameObject].
+     *
+     * If the [Object] is not a [GameObject], returns `nil`.
+     *
+     * @return [GameObject] gameObject : the [Object] as a [GameObject], or `nil`
+     */
     int ToGameObject(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->ToGameObject());
         return 1;
     }
 
+    /**
+     * Attempts to convert the [Object] to a [Unit].
+     *
+     * If the [Object] is not a [Unit], returns `nil`.
+     *
+     * @return [Unit] unit : the [Object] as a [Unit], or `nil`
+     */
     int ToUnit(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->ToUnit());
         return 1;
     }
 
+    /**
+     * Attempts to convert the [Object] to a [Creature].
+     *
+     * If the [Object] is not a [Creature], returns `nil`.
+     *
+     * @return [Creature] creature : the [Object] as a [Creature], or `nil`
+     */
     int ToCreature(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->ToCreature());
         return 1;
     }
 
+    /**
+     * Attempts to convert the [Object] to a [Player].
+     *
+     * If the [Object] is not a [Player], returns `nil`.
+     *
+     * @return [Player] player : the [Object] as a [Player], or `nil`
+     */
     int ToPlayer(Eluna* /*E*/, lua_State* L, Object* obj)
     {
         Eluna::Push(L, obj->ToPlayer());