(L, 1);
luaL_checktype(L, 2, LUA_TFUNCTION);
@@ -501,67 +512,65 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a server event
+ * Registers a server event handler.
*
- *
- * enum ServerEvents
- * {
- * // Server
- * SERVER_EVENT_ON_NETWORK_START = 1, // Not Implemented
- * SERVER_EVENT_ON_NETWORK_STOP = 2, // Not Implemented
- * SERVER_EVENT_ON_SOCKET_OPEN = 3, // Not Implemented
- * SERVER_EVENT_ON_SOCKET_CLOSE = 4, // Not Implemented
- * SERVER_EVENT_ON_PACKET_RECEIVE = 5, // (event, packet, player) - Player only if accessible. Can return false or a new packet
- * SERVER_EVENT_ON_PACKET_RECEIVE_UNKNOWN = 6, // Not Implemented
- * SERVER_EVENT_ON_PACKET_SEND = 7, // (event, packet, player) - Player only if accessible. Can return false or a new packet
+ * enum ServerEvents
+ * {
+ * // Server
+ * SERVER_EVENT_ON_NETWORK_START = 1, // Not Implemented
+ * SERVER_EVENT_ON_NETWORK_STOP = 2, // Not Implemented
+ * SERVER_EVENT_ON_SOCKET_OPEN = 3, // Not Implemented
+ * SERVER_EVENT_ON_SOCKET_CLOSE = 4, // Not Implemented
+ * SERVER_EVENT_ON_PACKET_RECEIVE = 5, // (event, packet, player) - Player only if accessible. Can return false or a new packet
+ * SERVER_EVENT_ON_PACKET_RECEIVE_UNKNOWN = 6, // Not Implemented
+ * SERVER_EVENT_ON_PACKET_SEND = 7, // (event, packet, player) - Player only if accessible. Can return false or a new packet
*
- * // World
- * WORLD_EVENT_ON_OPEN_STATE_CHANGE = 8, // (event, open) - Needs core support on Mangos
- * WORLD_EVENT_ON_CONFIG_LOAD = 9, // (event, reload)
- * // UNUSED = 10,
- * WORLD_EVENT_ON_SHUTDOWN_INIT = 11, // (event, code, mask)
- * WORLD_EVENT_ON_SHUTDOWN_CANCEL = 12, // (event)
- * WORLD_EVENT_ON_UPDATE = 13, // (event, diff)
- * WORLD_EVENT_ON_STARTUP = 14, // (event)
- * WORLD_EVENT_ON_SHUTDOWN = 15, // (event)
+ * // World
+ * WORLD_EVENT_ON_OPEN_STATE_CHANGE = 8, // (event, open) - Needs core support on Mangos
+ * WORLD_EVENT_ON_CONFIG_LOAD = 9, // (event, reload)
+ * // UNUSED = 10,
+ * WORLD_EVENT_ON_SHUTDOWN_INIT = 11, // (event, code, mask)
+ * WORLD_EVENT_ON_SHUTDOWN_CANCEL = 12, // (event)
+ * WORLD_EVENT_ON_UPDATE = 13, // (event, diff)
+ * WORLD_EVENT_ON_STARTUP = 14, // (event)
+ * WORLD_EVENT_ON_SHUTDOWN = 15, // (event)
*
- * // Eluna
- * ELUNA_EVENT_ON_LUA_STATE_CLOSE = 16, // (event) - triggers just before shutting down eluna (on shutdown and restart)
- * ELUNA_EVENT_ON_LUA_STATE_OPEN = 33, // (event) - triggers after all scripts are loaded
+ * // Eluna
+ * ELUNA_EVENT_ON_LUA_STATE_CLOSE = 16, // (event) - triggers just before shutting down eluna (on shutdown and restart)
+ * ELUNA_EVENT_ON_LUA_STATE_OPEN = 33, // (event) - triggers after all scripts are loaded
*
- * // Map
- * MAP_EVENT_ON_CREATE = 17, // (event, map)
- * MAP_EVENT_ON_DESTROY = 18, // (event, map)
- * MAP_EVENT_ON_GRID_LOAD = 19, // Not Implemented
- * MAP_EVENT_ON_GRID_UNLOAD = 20, // Not Implemented
- * MAP_EVENT_ON_PLAYER_ENTER = 21, // (event, map, player)
- * MAP_EVENT_ON_PLAYER_LEAVE = 22, // (event, map, player)
- * MAP_EVENT_ON_UPDATE = 23, // (event, map, diff)
+ * // Map
+ * MAP_EVENT_ON_CREATE = 17, // (event, map)
+ * MAP_EVENT_ON_DESTROY = 18, // (event, map)
+ * MAP_EVENT_ON_GRID_LOAD = 19, // Not Implemented
+ * MAP_EVENT_ON_GRID_UNLOAD = 20, // Not Implemented
+ * MAP_EVENT_ON_PLAYER_ENTER = 21, // (event, map, player)
+ * MAP_EVENT_ON_PLAYER_LEAVE = 22, // (event, map, player)
+ * MAP_EVENT_ON_UPDATE = 23, // (event, map, diff)
*
- * // Area trigger
- * TRIGGER_EVENT_ON_TRIGGER = 24, // (event, player, triggerId)
+ * // Area trigger
+ * TRIGGER_EVENT_ON_TRIGGER = 24, // (event, player, triggerId)
*
- * // Weather
- * WEATHER_EVENT_ON_CHANGE = 25, // (event, weather, state, grade)
+ * // Weather
+ * WEATHER_EVENT_ON_CHANGE = 25, // (event, weather, state, grade)
*
- * // Auction house
- * AUCTION_EVENT_ON_ADD = 26, // (event, AHObject)
- * AUCTION_EVENT_ON_REMOVE = 27, // (event, AHObject)
- * AUCTION_EVENT_ON_SUCCESSFUL = 28, // (event, AHObject) // Not Implemented
- * AUCTION_EVENT_ON_EXPIRE = 29, // (event, AHObject) // Not Implemented
+ * // Auction house
+ * AUCTION_EVENT_ON_ADD = 26, // (event, AHObject)
+ * AUCTION_EVENT_ON_REMOVE = 27, // (event, AHObject)
+ * AUCTION_EVENT_ON_SUCCESSFUL = 28, // (event, AHObject) // Not Implemented
+ * AUCTION_EVENT_ON_EXPIRE = 29, // (event, AHObject) // Not Implemented
*
- * // AddOns
- * ADDON_EVENT_ON_MESSAGE = 30, // (event, sender, type, prefix, msg, target) - target can be nil/whisper_target/guild/group/channel
+ * // AddOns
+ * ADDON_EVENT_ON_MESSAGE = 30, // (event, sender, type, prefix, msg, target) - target can be nil/whisper_target/guild/group/channel
*
- * WORLD_EVENT_ON_DELETE_CREATURE = 31, // (event, creature)
- * WORLD_EVENT_ON_DELETE_GAMEOBJECT = 32, // (event, gameobject)
+ * WORLD_EVENT_ON_DELETE_CREATURE = 31, // (event, creature)
+ * WORLD_EVENT_ON_DELETE_GAMEOBJECT = 32, // (event, gameobject)
*
- * SERVER_EVENT_COUNT
- * };
- *
+ * SERVER_EVENT_COUNT
+ * };
*
- * @param uint32 event : server event Id, refer to ServerEvents above
- * @param function function : function to register
+ * @param uint32 event : server event ID, refer to ServerEvents above
+ * @param function function : function that will be called when the event occurs
* @param uint32 shots = 0 : the number of times the function will be called, 0 means "always call this function"
*/
int RegisterServerEvent(Eluna* E, lua_State* L)
@@ -571,7 +580,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Player] event
+ * Registers a [Player] event handler.
*
*
* enum PlayerEvents
@@ -636,7 +645,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Guild] event
+ * Registers a [Guild] event handler.
*
*
* enum GuildEvents
@@ -669,7 +678,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Group] event
+ * Registers a [Group] event handler.
*
*
* enum GroupEvents
@@ -697,7 +706,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Battleground] event
+ * Registers a [BattleGround] event handler.
*
*
* enum BGEvents
@@ -721,7 +730,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a packet event
+ * Registers a [WorldPacket] event handler.
*
*
* enum PacketEvents
@@ -746,7 +755,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Creature] gossip event
+ * Registers a [Creature] gossip event handler.
*
*
* enum GossipEvents
@@ -769,7 +778,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [GameObject] gossip event
+ * Registers a [GameObject] gossip event handler.
*
*
* enum GossipEvents
@@ -792,7 +801,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers an [Item] event
+ * Registers an [Item] event handler.
*
*
* enum ItemEvents
@@ -818,7 +827,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers an [Item] gossip event
+ * Registers an [Item] gossip event handler.
*
*
* enum GossipEvents
@@ -841,7 +850,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Player] gossip event
+ * Registers a [Player] gossip event handler.
*
*
* enum GossipEvents
@@ -864,7 +873,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [Creature] event
+ * Registers a [Creature] event handler.
*
*
* enum CreatureEvents
@@ -922,7 +931,7 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a [GameObject] event
+ * Registers a [GameObject] event handler.
*
*
* enum GameObjectEvents
@@ -956,8 +965,7 @@ namespace LuaGlobalFunctions
}
/**
- * Reloads the Lua Engine
- *
+ * Reloads the Lua engine.
*/
int ReloadEluna(Eluna* /*E*/, lua_State* /*L*/)
{
@@ -966,7 +974,7 @@ namespace LuaGlobalFunctions
}
/**
- * Sends a message to the world
+ * Sends a message to all [Player]s online.
*
* @param string message : message to send
*/
@@ -978,10 +986,13 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your world database instantly and returns [ElunaQuery]
+ * Executes a SQL query on the world database and returns an [ElunaQuery].
*
- * @param string sql : sql to run
- * @return [ElunaQuery] result
+ * The query is always executed synchronously
+ * (i.e. when this function returns the query has already been executed).
+ *
+ * @param string sql : query to execute
+ * @return [ElunaQuery] results
*/
int WorldDBQuery(Eluna* /*E*/, lua_State* L)
{
@@ -1004,9 +1015,15 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your character database. The SQL is not ran instantly.
+ * Executes a SQL query on the world database.
*
- * @param string sql : sql [ElunaQuery] to execute
+ * The query may be executed *asynchronously* (at a later, unpredictable time).
+ * If you need to execute the query synchronously, use [Global:WorldDBQuery] instead.
+ *
+ * Any results produced are ignored.
+ * If you need results from the query, use [Global:WorldDBQuery] instead.
+ *
+ * @param string sql : query to execute
*/
int WorldDBExecute(Eluna* /*E*/, lua_State* L)
{
@@ -1016,10 +1033,13 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your character database instantly and returns [ElunaQuery]
+ * Executes a SQL query on the character database and returns an [ElunaQuery].
*
- * @param string sql : sql to run
- * @return [ElunaQuery] result
+ * The query is always executed synchronously
+ * (i.e. when this function returns the query has already been executed).
+ *
+ * @param string sql : query to execute
+ * @return [ElunaQuery] results
*/
int CharDBQuery(Eluna* /*E*/, lua_State* L)
{
@@ -1042,9 +1062,15 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your character database. The SQL is not ran instantly.
+ * Executes a SQL query on the character database.
*
- * @param string sql : sql to run
+ * The query may be executed *asynchronously* (at a later, unpredictable time).
+ * If you need to execute the query synchronously, use [Global:WorldDBQuery] instead.
+ *
+ * Any results produced are ignored.
+ * If you need results from the query, use [Global:WorldDBQuery] instead.
+ *
+ * @param string sql : query to execute
*/
int CharDBExecute(Eluna* /*E*/, lua_State* L)
{
@@ -1054,10 +1080,13 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your auth database instantly and returns [ElunaQuery]
+ * Executes a SQL query on the login database and returns an [ElunaQuery].
*
- * @param string sql : sql to run
- * @return [ElunaQuery] result
+ * The query is always executed synchronously
+ * (i.e. when this function returns the query has already been executed).
+ *
+ * @param string sql : query to execute
+ * @return [ElunaQuery] results
*/
int AuthDBQuery(Eluna* /*E*/, lua_State* L)
{
@@ -1080,9 +1109,15 @@ namespace LuaGlobalFunctions
}
/**
- * Executes an sql to your auth database. The SQL is not ran instantly.
+ * Executes a SQL query on the login database.
*
- * @param string sql : sql to run
+ * The query may be executed *asynchronously* (at a later, unpredictable time).
+ * If you need to execute the query synchronously, use [Global:WorldDBQuery] instead.
+ *
+ * Any results produced are ignored.
+ * If you need results from the query, use [Global:WorldDBQuery] instead.
+ *
+ * @param string sql : query to execute
*/
int AuthDBExecute(Eluna* /*E*/, lua_State* L)
{
@@ -1092,8 +1127,10 @@ namespace LuaGlobalFunctions
}
/**
- * Registers a global timed event
+ * Registers a global timed event.
+ *
* When the passed function is called, the parameters `(eventId, delay, repeats)` are passed to it.
+ *
* Repeats will decrease on each call if the event does not repeat indefinitely
*
* @param function function : function to trigger when the time has passed
@@ -1118,7 +1155,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes a global timed event specified by the event ID
+ * Removes a global timed event specified by ID.
*
* @param int eventId : event Id to remove
* @param bool all_Events = false : remove from all events, not just global
@@ -1137,7 +1174,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes all global timed events
+ * Removes all global timed events.
*
* @param bool all_Events = false : remove all events, not just global
*/
@@ -1154,7 +1191,7 @@ namespace LuaGlobalFunctions
}
/**
- * Performs an ingame spawn and returns [Creature] or [GameObject] dependent on spawnType
+ * Performs an in-game spawn and returns the [Creature] or [GameObject] spawned.
*
* @param int32 spawnType : type of object to spawn, 1 = [Creature], 2 = [GameObject]
* @param uint32 entry : entry ID of the [Creature] or [GameObject]
@@ -1484,10 +1521,10 @@ namespace LuaGlobalFunctions
}
/**
- * Creates a [WorldPacket]
+ * Creates a [WorldPacket].
*
- * @param uint32 opcode : opcode to create
- * @param uint32 size : size of opcode
+ * @param uint32 opcode : the opcode of the packet
+ * @param uint32 size : the size of the packet
* @return [WorldPacket] packet
*/
int CreatePacket(Eluna* /*E*/, lua_State* L)
@@ -1502,7 +1539,7 @@ namespace LuaGlobalFunctions
}
/**
- * Adds an [Item] to a vendor
+ * Adds an [Item] to a vendor and updates the world database.
*
* @param uint32 entry : [Creature] entry Id
* @param uint32 item : [Item] entry Id
@@ -1541,7 +1578,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes an [Item] from a vendor
+ * Removes an [Item] from a vendor and updates the database.
*
* @param uint32 entry : [Creature] entry Id
* @param uint32 item : [Item] entry Id
@@ -1562,7 +1599,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes all [Item]s from a vendor
+ * Removes all [Item]s from a vendor and updates the database.
*
* @param uint32 entry : [Creature] entry Id
*/
@@ -1585,7 +1622,7 @@ namespace LuaGlobalFunctions
}
/**
- * Kicks a [Player] from the server
+ * Kicks a [Player] from the server.
*
* @param [Player] player : [Player] to kick
*/
@@ -1599,14 +1636,12 @@ namespace LuaGlobalFunctions
/**
* Ban's a [Player]'s account, character or IP
*
- *
- * enum BanMode
- * {
- * BAN_ACCOUNT,
- * BAN_CHARACTER,
- * BAN_IP
- * };
- *
+ * enum BanMode
+ * {
+ * BAN_ACCOUNT,
+ * BAN_CHARACTER,
+ * BAN_IP
+ * };
*
* @param int32 banMode : method of ban, refer to BanMode above
* @param string nameOrIP : name of the [Player] or IP of the [Player]
@@ -1650,8 +1685,7 @@ namespace LuaGlobalFunctions
}
/**
- * Saves all [Player]s
- *
+ * Saves all [Player]s.
*/
int SaveAllPlayers(Eluna* /*E*/, lua_State* /*L*/)
{
@@ -1660,21 +1694,21 @@ namespace LuaGlobalFunctions
}
/**
- * Sends mail to a [Player]
- * There can be several item entry-amount pairs at the end of the function. There can be maximum of 12 different items.
+ * Sends mail to a [Player].
*
- *
- * enum MailStationery
- * {
- * MAIL_STATIONERY_TEST = 1,
- * MAIL_STATIONERY_DEFAULT = 41,
- * MAIL_STATIONERY_GM = 61,
- * MAIL_STATIONERY_AUCTION = 62,
- * MAIL_STATIONERY_VAL = 64, // Valentine
- * MAIL_STATIONERY_CHR = 65, // Christmas
- * MAIL_STATIONERY_ORP = 67 // Orphan
- * };
- *
+ * There can be several item entry-amount pairs at the end of the function.
+ * There can be maximum of 12 different items.
+ *
+ * enum MailStationery
+ * {
+ * MAIL_STATIONERY_TEST = 1,
+ * MAIL_STATIONERY_DEFAULT = 41,
+ * MAIL_STATIONERY_GM = 61,
+ * MAIL_STATIONERY_AUCTION = 62,
+ * MAIL_STATIONERY_VAL = 64, // Valentine
+ * MAIL_STATIONERY_CHR = 65, // Christmas
+ * MAIL_STATIONERY_ORP = 67 // Orphan
+ * };
*
* @param string subject : title (subject) of the mail
* @param string text : contents of the mail
@@ -1761,7 +1795,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise and: a & b
+ * Performs a bitwise AND (a & b).
*
* @param uint32 a
* @param uint32 b
@@ -1776,7 +1810,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise or: a | b
+ * Performs a bitwise OR (a | b).
*
* @param uint32 a
* @param uint32 b
@@ -1791,7 +1825,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise left shift: a << b
+ * Performs a bitwise left-shift (a << b).
*
* @param uint32 a
* @param uint32 b
@@ -1806,7 +1840,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise right shift: a >> b
+ * Performs a bitwise right-shift (a >> b).
*
* @param uint32 a
* @param uint32 b
@@ -1821,7 +1855,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise xor: a ^ b
+ * Performs a bitwise XOR (a ^ b).
*
* @param uint32 a
* @param uint32 b
@@ -1836,7 +1870,7 @@ namespace LuaGlobalFunctions
}
/**
- * Returns the result of bitwise not: ~a
+ * Performs a bitwise NOT (~a).
*
* @param uint32 a
* @return uint32 result
@@ -1849,16 +1883,16 @@ namespace LuaGlobalFunctions
}
/**
- * Adds a taxi path to a specified map, returns the used pathId
+ * Adds a taxi path to a specified map, returns the used pathId.
+ *
* Related function: [Player:StartTaxi]
*
- *
- * -- Execute on startup
- * local pathTable = {{mapid, x, y, z}, {mapid, x, y, z}}
- * local path = AddTaxiPath(pathTable, 28135, 28135)
- * -- Execute when the player should fly
- * player:StartTaxi(path)
- *
+ * -- Execute on startup
+ * local pathTable = {{mapid, x, y, z}, {mapid, x, y, z}}
+ * local path = AddTaxiPath(pathTable, 28135, 28135)
+ *
+ * -- Execute when the player should fly
+ * player:StartTaxi(path)
*
* @param table waypoints : table containing waypoints: {map, x, y, z[, actionFlag, delay]}
* @param uint32 mountA : alliance [Creature] entry
@@ -1965,7 +1999,7 @@ namespace LuaGlobalFunctions
}
/**
- * Adds a [Corpse] to the world
+ * Adds a [Corpse] to the world.
*
* @param [Corpse] corpse : [Corpse] to add
*/
@@ -1978,7 +2012,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes a [Corpse] from the world
+ * Removes a [Corpse] from the world.
*
* @param [Corpse] corpse : [Corpse] to remove
*/
@@ -1991,10 +2025,10 @@ namespace LuaGlobalFunctions
}
/**
- * Converts a [Corpse] by guid, also allows for insignia to be looted
+ * Converts a [Corpse] by GUID, and optionally allows for insignia to be looted.
*
- * @param uint64 playerGUID : guid of the [Player]
- * @param bool insignia = false : if true, it allows insignia to be looted
+ * @param uint64 playerGUID : GUID of the [Player]
+ * @param bool insignia = false : if `true`, allow an insignia to be looted
* @return [Corpse] corpse : returns converted [Corpse]
*/
int ConvertCorpseForPlayer(Eluna* /*E*/, lua_State* L)
@@ -2007,8 +2041,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes old [Corpse]s from the world
- *
+ * Removes old [Corpse]s from the world.
*/
int RemoveOldCorpses(Eluna* /*E*/, lua_State* /*L*/)
{
@@ -2017,7 +2050,7 @@ namespace LuaGlobalFunctions
}
/**
- * Finds [Weather] in a zone, also returns [Weather]
+ * Gets the [Weather] for a zone.
*
* @param uint32 zoneId : zone Id to check for [Weather]
* @return [Weather] weather
@@ -2035,7 +2068,7 @@ namespace LuaGlobalFunctions
}
/**
- * Adds [Weather] to a zone, also returns [Weather]
+ * Adds weather to a zone and returns the new [Weather] object.
*
* @param uint32 zoneId : zone Id to add [Weather]
* @return [Weather] weather
@@ -2053,7 +2086,7 @@ namespace LuaGlobalFunctions
}
/**
- * Removes [Weather] from a zone
+ * Removes [Weather] from a zone.
*
* @param uint32 zoneId : zone Id to remove [Weather]
*/
@@ -2069,7 +2102,9 @@ namespace LuaGlobalFunctions
}
/**
- * Sends normal [Weather] to a [Player]
+ * Sends a clear weather packet to a [Player].
+ *
+ * Does not affect other [Player]s in the same zone, or affect the zone.
*
* @param [Player] player : [Player] to send the normal weather to
*/
@@ -2085,25 +2120,26 @@ namespace LuaGlobalFunctions
}
/**
- * Returns true if the bag and slot is a valid inventory position, otherwise false
+ * Returns `true` if the bag and slot is a valid inventory position, otherwise `false`.
*
- *
- * Possible and most commonly used combinations:
+ * Some commonly used combinations:
*
- * bag = 255
- * slots 0-18 equipment
- * slots 19-22 equipped bag slots
- * slots 23-38 backpack
- * slots 39-66 bank main slots
- * slots 67-74 bank bag slots
- * slots 86-117 keyring
+ * *Bag 255 (common character inventory)*
*
- * bag = 19-22
- * slots 0-35 for equipped bags
+ * - Slots 0-18: equipment
+ * - Slots 19-22: bag slots
+ * - Slots 23-38: backpack
+ * - Slots 39-66: bank main slots
+ * - Slots 67-74: bank bag slots
+ * - Slots 86-117: keyring
*
- * bag = 67-74
- * slots 0-35 for bank bags
- *
+ * *Bags 19-22 (equipped bags)*
+ *
+ * - Slots 0-35
+ *
+ * *Bags 67-74 (bank bags)*
+ *
+ * - Slots 0-35
*
* @param uint8 bag : the bag the [Item] is in, you can get this with [Item:GetBagSlot]
* @param uint8 slot : the slot the [Item] is in within the bag, you can get this with [Item:GetSlot]
@@ -2119,25 +2155,9 @@ namespace LuaGlobalFunctions
}
/**
- * Returns true if the bag and slot is a valid equipment position, otherwise false
+ * Returns `true` if the bag and slot is a valid equipment position, otherwise `false`.
*
- *
- * Possible and most commonly used combinations:
- *
- * bag = 255
- * slots 0-18 equipment
- * slots 19-22 equipped bag slots
- * slots 23-38 backpack
- * slots 39-66 bank main slots
- * slots 67-74 bank bag slots
- * slots 86-117 keyring
- *
- * bag = 19-22
- * slots 0-35 for equipped bags
- *
- * bag = 67-74
- * slots 0-35 for bank bags
- *
+ * See [Global:IsInventoryPos] for bag/slot combination examples.
*
* @param uint8 bag : the bag the [Item] is in, you can get this with [Item:GetBagSlot]
* @param uint8 slot : the slot the [Item] is in within the bag, you can get this with [Item:GetSlot]
@@ -2153,25 +2173,9 @@ namespace LuaGlobalFunctions
}
/**
- * Returns true if the bag and slot is a valid bank position, otherwise false
+ * Returns `true` if the bag and slot is a valid bank position, otherwise `false`.
*
- *
- * Possible and most commonly used combinations:
- *
- * bag = 255
- * slots 0-18 equipment
- * slots 19-22 equipped bag slots
- * slots 23-38 backpack
- * slots 39-66 bank main slots
- * slots 67-74 bank bag slots
- * slots 86-117 keyring
- *
- * bag = 19-22
- * slots 0-35 for equipped bags
- *
- * bag = 67-74
- * slots 0-35 for bank bags
- *
+ * See [Global:IsInventoryPos] for bag/slot combination examples.
*
* @param uint8 bag : the bag the [Item] is in, you can get this with [Item:GetBagSlot]
* @param uint8 slot : the slot the [Item] is in within the bag, you can get this with [Item:GetSlot]
@@ -2187,25 +2191,9 @@ namespace LuaGlobalFunctions
}
/**
- * Returns true if the bag and slot is a valid bag position, otherwise false
+ * Returns `true` if the bag and slot is a valid bag position, otherwise `false`.
*
- *
- * Possible and most commonly used combinations:
- *
- * bag = 255
- * slots 0-18 equipment
- * slots 19-22 equipped bag slots
- * slots 23-38 backpack
- * slots 39-66 bank main slots
- * slots 67-74 bank bag slots
- * slots 86-117 keyring
- *
- * bag = 19-22
- * slots 0-35 for equipped bags
- *
- * bag = 67-74
- * slots 0-35 for bank bags
- *
+ * See [Global:IsInventoryPos] for bag/slot combination examples.
*
* @param uint8 bag : the bag the [Item] is in, you can get this with [Item:GetBagSlot]
* @param uint8 slot : the slot the [Item] is in within the bag, you can get this with [Item:GetSlot]
@@ -2221,9 +2209,9 @@ namespace LuaGlobalFunctions
}
/**
- * Returns current time in ms
+ * Returns the server's current time.
*
- * @return uint32 currTime
+ * @return uint32 currTime : the current time, in milliseconds
*/
int GetCurrTime(Eluna* /*E*/, lua_State* L)
{
@@ -2232,10 +2220,10 @@ namespace LuaGlobalFunctions
}
/**
- * Returns difference from a [Global:GetCurrTime] time to now
+ * Returns the difference between an old timestamp and the current time.
*
- * @param uint32 oldTime
- * @return uint32 timeDiff
+ * @param uint32 oldTime : an old timestamp, in milliseconds
+ * @return uint32 timeDiff : the difference, in milliseconds
*/
int GetTimeDiff(Eluna* /*E*/, lua_State* L)
{
@@ -2245,7 +2233,7 @@ namespace LuaGlobalFunctions
return 1;
}
- std::string GetStackAsString(lua_State* L)
+ static std::string GetStackAsString(lua_State* L)
{
std::ostringstream oss;
int top = lua_gettop(L);
@@ -2258,9 +2246,9 @@ namespace LuaGlobalFunctions
}
/**
- * Prints given parameters to the info log
+ * Prints given parameters to the info log.
*
- * @param ... variableArguments
+ * @param ...
*/
int PrintInfo(Eluna* /*E*/, lua_State* L)
{
@@ -2269,9 +2257,9 @@ namespace LuaGlobalFunctions
}
/**
- * Prints given parameters to the error log
+ * Prints given parameters to the error log.
*
- * @param ... variableArguments
+ * @param ...
*/
int PrintError(Eluna* /*E*/, lua_State* L)
{
@@ -2280,9 +2268,9 @@ namespace LuaGlobalFunctions
}
/**
- * Prints given parameters to the debug log
+ * Prints given parameters to the debug log.
*
- * @param ... variableArguments
+ * @param ...
*/
int PrintDebug(Eluna* /*E*/, lua_State* L)
{
@@ -2291,16 +2279,17 @@ namespace LuaGlobalFunctions
}
/**
- * Returns an object represeting long long.
+ * Returns an object representing a `long long` (64-bit) value.
+ *
* The value by default is 0, but can be initialized to a value by passing a number or long long as a string.
*
* @proto value = ()
- * @proto value = (number)
- * @proto value = (longlong)
- * @proto value = (longlongstr)
- * @param int32 number : regular lua number
- * @param int64 longlong : a long long object
- * @param string longlongstr : a long long as a string
+ * @proto value = (n)
+ * @proto value = (n_ll)
+ * @proto value = (n_str)
+ * @param int32 n
+ * @param int64 n_ll
+ * @param string n_str
* @return int64 value
*/
int CreateLongLong(Eluna* /*E*/, lua_State* L)
@@ -2320,16 +2309,17 @@ namespace LuaGlobalFunctions
}
/**
- * Returns an object represeting unsigned long long.
+ * Returns an object representing an `unsigned long long` (64-bit) value.
+ *
* The value by default is 0, but can be initialized to a value by passing a number or unsigned long long as a string.
*
* @proto value = ()
- * @proto value = (number)
- * @proto value = (ulonglong)
- * @proto value = (ulonglongstr)
- * @param uint32 number : regular lua number
- * @param uint64 ulonglong : an unsigned long long object
- * @param string ulonglongstr : an unsigned long long as a string
+ * @proto value = (n)
+ * @proto value = (n_ull)
+ * @proto value = (n_str)
+ * @param uint32 n
+ * @param uint64 n_ull
+ * @param string n_str
* @return uint64 value
*/
int CreateULongLong(Eluna* /*E*/, lua_State* L)
diff --git a/LuaFunctions.cpp b/LuaFunctions.cpp
index f65523a..dc02d7d 100644
--- a/LuaFunctions.cpp
+++ b/LuaFunctions.cpp
@@ -1123,7 +1123,6 @@ ElunaRegister QueryMethods[] =
{ "GetFloat", &LuaQuery::GetFloat }, // :GetFloat(column) - returns the value of a float column
{ "GetDouble", &LuaQuery::GetDouble }, // :GetDouble(column) - returns the value of a double column
{ "GetString", &LuaQuery::GetString }, // :GetString(column) - returns the value of a string column, always returns a string
- { "GetCString", &LuaQuery::GetCString }, // :GetCString(column) - returns the value of a string column, can return nil
{ "IsNull", &LuaQuery::IsNull }, // :IsNull(column) - returns true if the column is null
{ NULL, NULL },
diff --git a/docs/DOC_GEN.md b/docs/DOC_GEN.md
index 60bd022..9665c32 100644
--- a/docs/DOC_GEN.md
+++ b/docs/DOC_GEN.md
@@ -1,35 +1,37 @@
-#Documentation generation
+# Documentation generation
-##Setting up
+## Setting up
- install [python](https://www.python.org/)(2)
- - when installing, tick to install the path variable
- - may need restart after for installation to properly take effect
+ - when installing, tick to install the path variable
+ - may need restart after for installation to properly take effect
- install a package manager like [pip](https://pip.pypa.io/en/latest/)
- - if installed pip and doesnt work, restart or try easy_install command
+ - if installed pip and doesnt work, restart or try easy_install command
- install the dependencies with manager
- - [Jinja2](https://pypi.python.org/pypi/Jinja2)
- - [typedecorator](https://pypi.python.org/pypi/typedecorator)
- - [markdown](https://pypi.python.org/pypi/Markdown)
+ - [Jinja2](https://pypi.python.org/pypi/Jinja2)
+ - [typedecorator](https://pypi.python.org/pypi/typedecorator)
+ - [markdown](https://pypi.python.org/pypi/Markdown)
-##Generating
+## Generating
- Run in cmd `python -m ElunaDoc` when at `\LuaEngine\docs\`
-##Documenting
-You can document functions in the Eluna source code. For examples, simply open a method header file.
+## Documenting
+You can document functions in the Eluna source code. For examples, simply open a method header file with docs.
+
+### Template
+Here are basic templates for a function. When defining a parameter or a return value, the type and value name are mandatory, unless the parameter type is ... (for variable arguments; don't include a name in this case).
-###Template
-Here are basic templates for a function. When defining a parameter or a return value, the type and value name are mandatory.
```c++
/**
- * Description.
+ * Short description (about 80 characters long).
*
* @param Type paramName
* @return Type returnName
*/
```
+
```c++
/**
- * Description.
+ * Short description (about 80 characters long).
*
* @param Type paramName = defaultValue : parameter description
* @return Type returnName : return value description
@@ -37,9 +39,10 @@ Here are basic templates for a function. When defining a parameter or a return v
```
This is a template for a function that takes in different parameters. When defining a parameter or a return value, the type and value name are mandatory.
+
```c++
/**
- * Description.
+ * Short description (about 80 characters long).
*
* @proto returnValue = (object)
* @proto returnValue = (x, y, z)
@@ -51,46 +54,59 @@ This is a template for a function that takes in different parameters. When defin
*/
```
-###Standard
+### Standard
A documentation comment block will always start with `/**` and end with `*/`.
All lines start with `*` character followed by one space before any content.
-The main description will start with uppercase letter and end with a dot. All paragraphs should end with a dot as well.
-The parameter and return value descriptions should start with a lowercase letter and at the end there should be no dot.
+The first paragrph is used as a short description of the function/class, so it should be kept to about 80 characters. The other paragraphs can be as long as desired.
+
+All paragraphs in the description (including the first) should start with a capital letter and end with a period.
+**Paragraphs must be separated by an empty line**, e.g.:
+
+```c++
+/**
+ * This is a short description (about 80 characters).
+ *
+ * Here's another paragraph with more info. NOTE THE EMPTY LINE BETWEEN THE PARAGRAPHS.
+ * This does need to be short, and this line is still part of the same paragraph because
+ * there is no empty line.
+ */
+ ```
+
+The parameter and return value descriptions should start with a lowercase letter and not end with a period. If more than one sentence is needed, start the *first* without a capital letter and end the *last* without a period.
Any class, enum or function can be referenced (made a link to) with square brackets.
`[Player]` will reference a player. `[WeatherType]` will reference an enum. `[Player:GetName]` will reference a function.
-Use correct indentation with documentation comments
+Use correct indentation with documentation comments.
+
```c++
/**
* Correct indentation.
- * @param Type paramName = defaultValue : parameter description
- * @return Type returnName : return value description
*/
```
+
```c++
/**
* Invalid indentation.
-* @param Type paramName = defaultValue : parameter description
-* @return Type returnName : return value description
*/
```
-###Markdown
+### Markdown
You can use [markdown](http://pythonhosted.org//Markdown/) in your descriptions.
For syntax see http://daringfireball.net/projects/markdown/syntax and http://pythonhosted.org//Markdown/#differences
+
```
/**
* Description.
*
- * * list item
- * * list item
- * * list item
+ * - list item
+ * - list item
+ * - list item
*
- *
- * codeblock
- *
+ * // Codeblock
+ * // Code goes here.
+ * // Note the 4-space indent.
*
* `code line`
*
@@ -98,24 +114,27 @@ For syntax see http://daringfireball.net/projects/markdown/syntax and http://pyt
* **bold**
*/
```
-Produces
+
+**Produces:**
+
Description.
-* list item
-* list item
-* list item
+- list item
+- list item
+- list item
-
-codeblock
-
+ // Codeblock
+ // Code goes here.
+ // Note the 4-space indent.
`code line`
*italic*
**bold**
-###Types
-Here are some examples of possible types and most commonly used ones
+### Types
+Here are some examples of possible types and most commonly used ones:
+
```
string
uint32
@@ -126,6 +145,7 @@ int16
int8
double
float
+...
[EnumName]
[Player]
[Creature]
@@ -134,4 +154,4 @@ float
[Unit]
[WorldObject]
[Object]
-```
+```
\ No newline at end of file
diff --git a/docs/ElunaDoc/parser.py b/docs/ElunaDoc/parser.py
index a8308cf..c994cb3 100644
--- a/docs/ElunaDoc/parser.py
+++ b/docs/ElunaDoc/parser.py
@@ -22,13 +22,18 @@ class ParameterDoc(object):
'uint64': ('0', '18,446,744,073,709,551,615'),
}
- @params(self=object, name=unicode, data_type=str, description=unicode, default_value=Nullable(unicode))
+ @params(self=object, name=Nullable(unicode), data_type=str, description=unicode, default_value=Nullable(unicode))
def __init__(self, name, data_type, description, default_value=None):
"""If `name` is not provided, the Parameter is a returned value instead of a parameter."""
self.name = name
self.data_type = data_type
self.default_value = default_value
+ if self.data_type == '...':
+ self.name = '...'
+ else:
+ assert(self.name is not None)
+
if description:
# Capitalize the first letter, add a period, and parse as Markdown.
self.description = '{}{}. '.format(description[0].capitalize(), description[1:])
@@ -114,7 +119,7 @@ class ClassParser(object):
# An extra optional space (\s?) was thrown in to make it different from `class_body_regex`.
param_regex = re.compile(r"""\s*\*\s@param\s # The @param tag starts with opt. whitespace followed by "* @param ".
- ([^\s]+)\s(\w+) # The data type, a space, and the name of the param.
+ ([^\s]+)\s(\w+)? # The data type, a space, and the name of the param.
(?:\s=\s(\w+))? # The default value: a = surrounded by spaces, followed by text.
(?:\s:\s(.+))? # The description: a colon surrounded by spaces, followed by text.
""", re.X)
@@ -172,16 +177,15 @@ class ClassParser(object):
def handle_proto(self, match):
return_values, parameters = match.group(1), match.group(2)
- prototype = '{0}= {1}:{{0}}( {2} )'.format(return_values, self.class_name, parameters)
+ parameters = ' '+parameters+' ' if parameters else ''
+ return_values = return_values + '= ' if return_values else ''
+ prototype = '{0}{1}:{{0}}({2})'.format(return_values, self.class_name, parameters)
self.prototypes.append(prototype)
def handle_end(self, match):
self.method_name = match.group(1)
- # If there's no prototype, make one with all params and returns.
- if not self.prototypes:
- parameters = ', '.join([param.name for param in self.params])
- # Only pad with spaces when there are no parameters.
+ def make_prototype(parameters):
if parameters != '':
parameters = ' ' + parameters + ' '
@@ -198,7 +202,37 @@ class ClassParser(object):
else:
prototype = '{0}:{1}({2})'.format(self.class_name, self.method_name, parameters)
- self.prototypes.append(prototype)
+ return prototype
+
+ # If there's no prototype, make one with all params and returns.
+ if not self.prototypes:
+ # A list of all parameters with default values.
+ params_with_default = []
+ # The index of the last non-default parameter.
+ last_non_default_i = 0
+ # If False, a parameter WITHOUT a default value follows one WITH a default value.
+ # In this case, don't bother generating prototypes.
+ simple_order = True
+
+ for i, param in enumerate(self.params):
+ if param.default_value:
+ params_with_default.append(param)
+ else:
+ last_non_default_i = i
+ if params_with_default:
+ simple_order = False
+
+ if not params_with_default or not simple_order:
+ # Just generate one prototype with all the parameters.
+ parameters = ', '.join([param.name for param in self.params])
+ self.prototypes.append(make_prototype(parameters))
+ else:
+ # Generate a prototype for all the non-default parameters,
+ # then one for each default parameter with all the previous parameters.
+ for i in range(last_non_default_i, len(self.params)):
+ parameters = ', '.join([param.name for param in self.params[:i+1]])
+ self.prototypes.append(make_prototype(parameters))
+
else:
# Format the method name into each prototype.
self.prototypes = [proto.format(self.method_name) for proto in self.prototypes]
@@ -220,7 +254,7 @@ class ClassParser(object):
}
# Table of which regular expressions can follow the last handled regex.
- # `doc_body_regex` must always come LAST when used, since it also matches param, return, and comment_end.
+ # `body_regex` must always come LAST when used, since it also matches param, return, and comment_end.
next_regexes = {
None: [class_start_regex, start_regex, end_regex],
class_start_regex: [class_end_regex, class_body_regex],
diff --git a/docs/ElunaDoc/templates/method.html b/docs/ElunaDoc/templates/method.html
index ce7b701..40d7d04 100644
--- a/docs/ElunaDoc/templates/method.html
+++ b/docs/ElunaDoc/templates/method.html
@@ -53,7 +53,7 @@
{%- if current_method.parameters|length > 0 %}
{%- for param in current_method.parameters %}
- {{ param.data_type|escape|parse_data_type }} {{ param.name }} {{- ' (' + param.default_value + ')' if param.default_value }}{{ param.data_type|escape|parse_data_type }} {{ param.name if param.data_type != '...' }} {{- ' (' + param.default_value + ')' if param.default_value }}- {{ param.description|parse_links if param.description else 'See method description.' }}
{%- endfor %}