yolinlin/mod-ale
1
0
Fork 0
mirror of https://github.com/azerothcore/mod-ale synced 2025-11-29 15:38:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/elunaluaengine/eluna

Browse Source
This commit is contained in:
Foereaper
2014-12-22 04:55:08 +01:00
parent 7ce8db73b9 bce49b99e2
commit 8238ac05ca
10 changed files with 594 additions and 444 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
BattleGroundMethods.h
View File

@@ -7,10 +7,13 @@
#ifndef BATTLEGROUNDMETHODS_H #ifndef BATTLEGROUNDMETHODS_H
#define BATTLEGROUNDMETHODS_H #define BATTLEGROUNDMETHODS_H
/***
* Contains the state of a battleground, e.g. Warsong Gulch, Arathi Basin, etc.
*/
namespace LuaBattleGround namespace LuaBattleGround
{ {
/** /**
* Returns the name of the [Battleground] * Returns the name of the [BattleGround].
* *
* @return string name * @return string name
*/ */
@@ -21,7 +24,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the amount of alive players in the [Battleground] by the team ID. * Returns the amount of alive players in the [BattleGround] by the team ID.
* *
* @param uint32 team : team ID * @param uint32 team : team ID
* @return uint32 count * @return uint32 count
@@ -35,7 +38,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the [Map] of the [Battleground]. * Returns the [Map] of the [BattleGround].
* *
* @return [Map] map * @return [Map] map
*/ */
@@ -46,7 +49,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the bonus honor given by amount of kills in the specific [Battleground]. * Returns the bonus honor given by amount of kills in the specific [BattleGround].
* *
* @param uint32 kills : amount of kills * @param uint32 kills : amount of kills
* @return uint32 bonusHonor * @return uint32 bonusHonor
@@ -60,7 +63,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the bracket ID of the specific [Battleground]. * Returns the bracket ID of the specific [BattleGround].
* *
* @return BattleGroundBracketId bracketId * @return BattleGroundBracketId bracketId
*/ */
@@ -71,7 +74,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the end time of the [Battleground]. * Returns the end time of the [BattleGround].
* *
* @return uint32 endTime * @return uint32 endTime
*/ */
@@ -86,7 +89,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the amount of free slots for the selected team in the specific [Battleground]. * Returns the amount of free slots for the selected team in the specific [BattleGround].
* *
* @param uint32 team : team ID * @param uint32 team : team ID
* @return uint32 freeSlots * @return uint32 freeSlots
@@ -100,7 +103,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the instance ID of the [Battleground]. * Returns the instance ID of the [BattleGround].
* *
* @return uint32 instanceId * @return uint32 instanceId
*/ */
@@ -111,7 +114,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the map ID of the [Battleground]. * Returns the map ID of the [BattleGround].
* *
* @return uint32 mapId * @return uint32 mapId
*/ */
@@ -122,7 +125,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the type ID of the [Battleground]. * Returns the type ID of the [BattleGround].
* *
* @return BattleGroundTypeId typeId * @return BattleGroundTypeId typeId
*/ */
@@ -133,7 +136,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the max allowed [Player] level of the specific [Battleground]. * Returns the max allowed [Player] level of the specific [BattleGround].
* *
* @return uint32 maxLevel * @return uint32 maxLevel
*/ */
@@ -144,7 +147,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the minimum allowed [Player] level of the specific [Battleground]. * Returns the minimum allowed [Player] level of the specific [BattleGround].
* *
* @return uint32 minLevel * @return uint32 minLevel
*/ */
@@ -155,7 +158,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the maximum allowed [Player] count of the specific [Battleground]. * Returns the maximum allowed [Player] count of the specific [BattleGround].
* *
* @return uint32 maxPlayerCount * @return uint32 maxPlayerCount
*/ */
@@ -166,7 +169,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the minimum allowed [Player] count of the specific [Battleground]. * Returns the minimum allowed [Player] count of the specific [BattleGround].
* *
* @return uint32 minPlayerCount * @return uint32 minPlayerCount
*/ */
@@ -177,7 +180,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the maximum allowed [Player] count per team of the specific [Battleground]. * Returns the maximum allowed [Player] count per team of the specific [BattleGround].
* *
* @return uint32 maxTeamPlayerCount * @return uint32 maxTeamPlayerCount
*/ */
@@ -188,7 +191,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the minimum allowed [Player] count per team of the specific [Battleground]. * Returns the minimum allowed [Player] count per team of the specific [BattleGround].
* *
* @return uint32 minTeamPlayerCount * @return uint32 minTeamPlayerCount
*/ */
@@ -199,7 +202,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the winning team of the specific [Battleground]. * Returns the winning team of the specific [BattleGround].
* *
* @return Team team * @return Team team
*/ */
@@ -210,7 +213,7 @@ namespace LuaBattleGround
} }
/** /**
* Returns the status of the specific [Battleground]. * Returns the status of the specific [BattleGround].
* *
* @return BattleGroundStatus status * @return BattleGroundStatus status
*/ */

31
CorpseMethods.h
View File

@@ -7,10 +7,13 @@
#ifndef CORPSEMETHODS_H #ifndef CORPSEMETHODS_H
#define CORPSEMETHODS_H #define CORPSEMETHODS_H
/***
* The remains of a [Player] that has died.
*/
namespace LuaCorpse namespace LuaCorpse
{ {
/** /**
* Returns the [Corpse] Owner GUID. * Returns the GUID of the [Player] that left the [Corpse] behind.
* *
* @return uint64 ownerGUID * @return uint64 ownerGUID
*/ */
@@ -25,7 +28,7 @@ namespace LuaCorpse
} }
/** /**
* Returns the ghost time of a [Corpse]. * Returns the time when the [Player] became a ghost and spawned this [Corpse].
* *
* @return uint32 ghostTime * @return uint32 ghostTime
*/ */
@@ -38,14 +41,12 @@ namespace LuaCorpse
/** /**
* Returns the [CorpseType] of a [Corpse]. * Returns the [CorpseType] of a [Corpse].
* *
* <pre> * enum CorpseType
* enum CorpseType * {
* { * CORPSE_BONES = 0,
* CORPSE_BONES = 0, * CORPSE_RESURRECTABLE_PVE = 1,
* CORPSE_RESURRECTABLE_PVE = 1, * CORPSE_RESURRECTABLE_PVP = 2
* CORPSE_RESURRECTABLE_PVP = 2 * };
* };
* </pre>
* *
* @return [CorpseType] corpseType * @return [CorpseType] corpseType
*/ */
@@ -56,8 +57,9 @@ namespace LuaCorpse
} }
/** /**
* Resets the [Corpse] ghost time. * Sets the "ghost time" to the current time.
* *
* See [Corpse:GetGhostTime].
*/ */
int ResetGhostTime(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse) int ResetGhostTime(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse)
{ {
@@ -67,7 +69,6 @@ namespace LuaCorpse
/** /**
* Saves the [Corpse] to the database. * Saves the [Corpse] to the database.
*
*/ */
int SaveToDB(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse) int SaveToDB(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse)
{ {
@@ -78,9 +79,15 @@ namespace LuaCorpse
/** /**
* Deletes the [Corpse] from the world. * Deletes the [Corpse] from the world.
* *
* If the [Corpse]'s type is not BONES then this does nothing.
*/ */
int DeleteBonesFromWorld(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse) int DeleteBonesFromWorld(Eluna* /*E*/, lua_State* /*L*/, Corpse* corpse)
{ {
// Prevent a failed assertion.
if (corpse->GetType() != CORPSE_BONES)
{
return 0;
}
corpse->DeleteBonesFromWorld(); corpse->DeleteBonesFromWorld();
return 0; return 0;
} }

4
CreatureMethods.h
View File

@@ -8,9 +8,9 @@
#define CREATUREMETHODS_H #define CREATUREMETHODS_H
/*** /***
* Non-[Player] controlled [Unit]s. * Non-[Player] controlled [Unit]s (i.e. NPCs).
* *
* Inherits [Object], [WorldObject], [Unit] * Inherits all [Object], [WorldObject], and [Unit] methods.
*/ */
namespace LuaCreature namespace LuaCreature
{ {

4
ElunaIncludes.h
View File

@@ -61,6 +61,10 @@
typedef Opcodes OpcodesList; typedef Opcodes OpcodesList;
#endif #endif
/*
* Note: if you add or change a CORE_NAME #define,
* please update LuaGlobalFunctions::GetCoreName docstring.
*/
#ifdef MANGOS #ifdef MANGOS
#define CORE_NAME "MaNGOS" #define CORE_NAME "MaNGOS"
#define CORE_VERSION REVISION_NR #define CORE_VERSION REVISION_NR

183
ElunaQueryMethods.h
View File

@@ -12,19 +12,31 @@
#else #else
#define RESULT (*result) #define RESULT (*result)
#endif #endif
/***
* The result of a database query.
*
* E.g. the return value of [Global:WorldDBQuery].
*/
namespace LuaQuery namespace LuaQuery
{ {
void CheckFields(Eluna* /*E*/, lua_State* L, ElunaQuery* result) static void CheckFields(lua_State* L, ElunaQuery* result)
{ {
if (Eluna::CHECKVAL<uint32>(L, 2) >= RESULT->GetFieldCount()) if (Eluna::CHECKVAL<uint32>(L, 2) >= RESULT->GetFieldCount())
luaL_argerror(L, 2, "invalid field index"); luaL_argerror(L, 2, "invalid field index");
} }
/* BOOLEAN */ /* BOOLEAN */
int IsNull(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns `true` if the specified column of the current row is `NULL`, otherwise `false`.
*
* @param uint32 column
* @return bool isNull
*/
int IsNull(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
#ifndef TRINITY #ifndef TRINITY
Eluna::Push(L, RESULT->Fetch()[col].IsNULL()); Eluna::Push(L, RESULT->Fetch()[col].IsNULL());
@@ -35,126 +47,195 @@ namespace LuaQuery
} }
/* GETTERS */ /* GETTERS */
/**
* Returns the number of columns in the result set.
*
* @return uint32 columnCount
*/
int GetColumnCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result) int GetColumnCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
Eluna::Push(L, RESULT->GetFieldCount()); Eluna::Push(L, RESULT->GetFieldCount());
return 1; return 1;
} }
/**
* Returns the number of rows in the result set.
*
* @return uint32 rowCount
*/
int GetRowCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result) int GetRowCount(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
if (RESULT->GetRowCount() > (uint32)-1) if (RESULT->GetRowCount() > (uint32)-1)
Eluna::Push(L, (uint32)-1); Eluna::Push(L, (uint32)-1);
else else
Eluna::Push(L, RESULT->GetRowCount()); Eluna::Push(L, (uint32)(RESULT->GetRowCount()));
return 1; return 1;
} }
int GetBool(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a boolean.
*
* @param uint32 column
* @return bool data
*/
int GetBool(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetBool()); Eluna::Push(L, RESULT->Fetch()[col].GetBool());
return 1; return 1;
} }
int GetUInt8(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to an unsigned 8-bit integer.
*
* @param uint32 column
* @return uint8 data
*/
int GetUInt8(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetUInt8()); Eluna::Push(L, RESULT->Fetch()[col].GetUInt8());
return 1; return 1;
} }
int GetUInt16(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to an unsigned 16-bit integer.
*
* @param uint32 column
* @return uint16 data
*/
int GetUInt16(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetUInt16()); Eluna::Push(L, RESULT->Fetch()[col].GetUInt16());
return 1; return 1;
} }
int GetUInt32(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to an unsigned 32-bit integer.
*
* @param uint32 column
* @return uint32 data
*/
int GetUInt32(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetUInt32()); Eluna::Push(L, RESULT->Fetch()[col].GetUInt32());
return 1; return 1;
} }
int GetUInt64(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to an unsigned 64-bit integer.
*
* @param uint32 column
* @return uint64 data
*/
int GetUInt64(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetUInt64()); Eluna::Push(L, RESULT->Fetch()[col].GetUInt64());
return 1; return 1;
} }
int GetInt8(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a signed 8-bit integer.
*
* @param uint32 column
* @return int8 data
*/
int GetInt8(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetInt8()); Eluna::Push(L, RESULT->Fetch()[col].GetInt8());
return 1; return 1;
} }
int GetInt16(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a signed 16-bit integer.
*
* @param uint32 column
* @return int16 data
*/
int GetInt16(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetInt16()); Eluna::Push(L, RESULT->Fetch()[col].GetInt16());
return 1; return 1;
} }
int GetInt32(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a signed 32-bit integer.
*
* @param uint32 column
* @return int32 data
*/
int GetInt32(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetInt32()); Eluna::Push(L, RESULT->Fetch()[col].GetInt32());
return 1; return 1;
} }
int GetInt64(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a signed 64-bit integer.
*
* @param uint32 column
* @return int64 data
*/
int GetInt64(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetInt64()); Eluna::Push(L, RESULT->Fetch()[col].GetInt64());
return 1; return 1;
} }
int GetFloat(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a 32-bit floating point value.
*
* @param uint32 column
* @return float data
*/
int GetFloat(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetFloat()); Eluna::Push(L, RESULT->Fetch()[col].GetFloat());
return 1; return 1;
} }
int GetDouble(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a 64-bit floating point value.
*
* @param uint32 column
* @return double data
*/
int GetDouble(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
Eluna::Push(L, RESULT->Fetch()[col].GetDouble()); Eluna::Push(L, RESULT->Fetch()[col].GetDouble());
return 1; return 1;
} }
int GetString(Eluna* E, lua_State* L, ElunaQuery* result) /**
* Returns the data in the specified column of the current row, casted to a string.
*
* @param uint32 column
* @return string data
*/
int GetString(Eluna* /*E*/, lua_State* L, ElunaQuery* result)
{ {
uint32 col = Eluna::CHECKVAL<uint32>(L, 2); uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result); CheckFields(L, result);
#ifndef TRINITY
Eluna::Push(L, RESULT->Fetch()[col].GetCppString());
#else
Eluna::Push(L, RESULT->Fetch()[col].GetString());
#endif
return 1;
}
int GetCString(Eluna* E, lua_State* L, ElunaQuery* result)
{
uint32 col = Eluna::CHECKVAL<uint32>(L, 2);
CheckFields(E, L, result);
#ifndef TRINITY #ifndef TRINITY
Eluna::Push(L, RESULT->Fetch()[col].GetString()); Eluna::Push(L, RESULT->Fetch()[col].GetString());
@@ -167,8 +248,11 @@ namespace LuaQuery
/* OTHER */ /* OTHER */
/** /**
* Advances the ElunaQuery to the next row in the result returned. * Advances the [ElunaQuery] to the next row in the result set.
* Returns false if there was no new row, otherwise true. *
* *Do not* call this immediately after a query, or you'll skip the first row.
*
* Returns `false` if there was no new row, otherwise `true`.
* *
* @return bool hadNextRow * @return bool hadNextRow
*/ */
@@ -180,9 +264,18 @@ namespace LuaQuery
/** /**
* Returns a table from the current row where keys are field names and values are the row's values. * Returns a table from the current row where keys are field names and values are the row's values.
*
* All numerical values will be numbers and everything else is returned as a string. * All numerical values will be numbers and everything else is returned as a string.
* For example `SELECT entry, name FROM creature_template` would result in a table of `{ entry = 123, name = "some creature name" }` *
* To move to next row see [ElunaQuery:NextRow] * **For example,** the query:
*
* SELECT entry, name FROM creature_template
*
* would result in a table like:
*
* { entry = 123, name = "some creature name" }
*
* To move to next row use [ElunaQuery:NextRow].
* *
* @return table rowData : table filled with row columns and data where `T[column] = data` * @return table rowData : table filled with row columns and data where `T[column] = data`
*/ */

620
GlobalMethods.h
View File

File diff suppressed because it is too large Load Diff

1
LuaFunctions.cpp
View File

@@ -1123,7 +1123,6 @@ ElunaRegister<ElunaQuery> QueryMethods[] =
{ "GetFloat", &LuaQuery::GetFloat }, // :GetFloat(column) - returns the value of a float column { "GetFloat", &LuaQuery::GetFloat }, // :GetFloat(column) - returns the value of a float column
{ "GetDouble", &LuaQuery::GetDouble }, // :GetDouble(column) - returns the value of a double 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 { "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 { "IsNull", &LuaQuery::IsNull }, // :IsNull(column) - returns true if the column is null
{ NULL, NULL }, { NULL, NULL },

102
docs/DOC_GEN.md
View File

@@ -1,35 +1,37 @@
#Documentation generation # Documentation generation
##Setting up ## Setting up
- install [python](https://www.python.org/)(2) - install [python](https://www.python.org/)(2)
- when installing, tick to install the path variable - when installing, tick to install the path variable
- may need restart after for installation to properly take effect - may need restart after for installation to properly take effect
- install a package manager like [pip](https://pip.pypa.io/en/latest/) - 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 - install the dependencies with manager
- [Jinja2](https://pypi.python.org/pypi/Jinja2) - [Jinja2](https://pypi.python.org/pypi/Jinja2)
- [typedecorator](https://pypi.python.org/pypi/typedecorator) - [typedecorator](https://pypi.python.org/pypi/typedecorator)
- [markdown](https://pypi.python.org/pypi/Markdown) - [markdown](https://pypi.python.org/pypi/Markdown)
##Generating ## Generating
- Run in cmd `python -m ElunaDoc` when at `\LuaEngine\docs\` - Run in cmd `python -m ElunaDoc` when at `\LuaEngine\docs\`
##Documenting ## Documenting
You can document functions in the Eluna source code. For examples, simply open a method header file. 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++ ```c++
/** /**
* Description. * Short description (about 80 characters long).
* *
* @param Type paramName * @param Type paramName
* @return Type returnName * @return Type returnName
*/ */
``` ```
```c++ ```c++
/** /**
* Description. * Short description (about 80 characters long).
* *
* @param Type paramName = defaultValue : parameter description * @param Type paramName = defaultValue : parameter description
* @return Type returnName : return value 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. 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++ ```c++
/** /**
* Description. * Short description (about 80 characters long).
* *
* @proto returnValue = (object) * @proto returnValue = (object)
* @proto returnValue = (x, y, z) * @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 `*/`. A documentation comment block will always start with `/**` and end with `*/`.
All lines start with `*` character followed by one space before any content. 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 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.
The parameter and return value descriptions should start with a lowercase letter and at the end there should be no dot.
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. 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. `[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++ ```c++
/** /**
* Correct indentation. * Correct indentation.
* @param Type paramName = defaultValue : parameter description
* @return Type returnName : return value description
*/ */
``` ```
```c++ ```c++
/** /**
* Invalid indentation. * 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. 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 For syntax see http://daringfireball.net/projects/markdown/syntax and http://pythonhosted.org//Markdown/#differences
``` ```
/** /**
* Description. * Description.
* *
* * list item * - list item
* * list item * - list item
* * list item * - list item
* *
* <pre> * // Codeblock
* codeblock * // Code goes here.
* </pre> * // Note the 4-space indent.
* *
* `code line` * `code line`
* *
@@ -98,24 +114,27 @@ For syntax see http://daringfireball.net/projects/markdown/syntax and http://pyt
* **bold** * **bold**
*/ */
``` ```
Produces<br/>
**Produces:**
Description. Description.
* list item - list item
* list item - list item
* list item - list item
<pre> // Codeblock
codeblock // Code goes here.
</pre> // Note the 4-space indent.
`code line` `code line`
*italic* *italic*
**bold** **bold**
###Types ### Types
Here are some examples of possible types and most commonly used ones Here are some examples of possible types and most commonly used ones:
``` ```
string string
uint32 uint32
@@ -126,6 +145,7 @@ int16
int8 int8
double double
float float
...
[EnumName] [EnumName]
[Player] [Player]
[Creature] [Creature]
@@ -134,4 +154,4 @@ float
[Unit] [Unit]
[WorldObject] [WorldObject]
[Object] [Object]
``` ```

52
docs/ElunaDoc/parser.py
View File

@@ -22,13 +22,18 @@ class ParameterDoc(object):
'uint64': ('0', '18,446,744,073,709,551,615'), '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): 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.""" """If `name` is not provided, the Parameter is a returned value instead of a parameter."""
self.name = name self.name = name
self.data_type = data_type self.data_type = data_type
self.default_value = default_value self.default_value = default_value
if self.data_type == '...':
self.name = '...'
else:
assert(self.name is not None)
if description: if description:
# Capitalize the first letter, add a period, and parse as Markdown. # Capitalize the first letter, add a period, and parse as Markdown.
self.description = '{}{}. '.format(description[0].capitalize(), description[1:]) 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`. # 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 ". 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(\w+))? # The default value: a = surrounded by spaces, followed by text.
(?:\s:\s(.+))? # The description: a colon surrounded by spaces, followed by text. (?:\s:\s(.+))? # The description: a colon surrounded by spaces, followed by text.
""", re.X) """, re.X)
@@ -172,16 +177,15 @@ class ClassParser(object):
def handle_proto(self, match): def handle_proto(self, match):
return_values, parameters = match.group(1), match.group(2) 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) self.prototypes.append(prototype)
def handle_end(self, match): def handle_end(self, match):
self.method_name = match.group(1) self.method_name = match.group(1)
# If there's no prototype, make one with all params and returns. def make_prototype(parameters):
if not self.prototypes:
parameters = ', '.join([param.name for param in self.params])
# Only pad with spaces when there are no parameters.
if parameters != '': if parameters != '':
parameters = ' ' + parameters + ' ' parameters = ' ' + parameters + ' '
@@ -198,7 +202,37 @@ class ClassParser(object):
else: else:
prototype = '{0}:{1}({2})'.format(self.class_name, self.method_name, parameters) 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: else:
# Format the method name into each prototype. # Format the method name into each prototype.
self.prototypes = [proto.format(self.method_name) for proto in self.prototypes] 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. # 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 = { next_regexes = {
None: [class_start_regex, start_regex, end_regex], None: [class_start_regex, start_regex, end_regex],
class_start_regex: [class_end_regex, class_body_regex], class_start_regex: [class_end_regex, class_body_regex],

2
docs/ElunaDoc/templates/method.html
View File

@@ -53,7 +53,7 @@
{%- if current_method.parameters|length > 0 %} {%- if current_method.parameters|length > 0 %}
{%- for param in current_method.parameters %} {%- for param in current_method.parameters %}
<dl> <dl>
<dt><code>{{ param.data_type|escape|parse_data_type }} {{ param.name }} {{- ' (' + param.default_value + ')' if param.default_value }}</code></dt> <dt><code>{{ param.data_type|escape|parse_data_type }} {{ param.name if param.data_type != '...' }} {{- ' (' + param.default_value + ')' if param.default_value }}</code></dt>
<dd class="docblock">{{ param.description|parse_links if param.description else '<em>See method description.</em>' }}</dd> <dd class="docblock">{{ param.description|parse_links if param.description else '<em>See method description.</em>' }}</dd>
</dl> </dl>
{%- endfor %} {%- endfor %}