flewkey/cuberite-2a
1
0
Fork 0
Code Releases Activity

Merge pull request #3376 from cuberite/LuaApiReformat

Browse Source 
Lua API description reformat
This commit is contained in:
Mattes D 2016-09-13 09:43:02 +02:00 committed by GitHub
commit ca99e754ea
13 changed files with 23452 additions and 2415 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CIbuild.sh
View File

@ -31,4 +31,9 @@ EOF
cat ./NewlyUndocumented.lua
exit 1
fi
if [ -f ./DuplicateDocs.txt ]; then
echo "ERROR: API documentation has duplicate symbol warnings:"
cat ./DuplicateDocs.txt
exit 1
fi
fi

1
Server/.gitignore vendored
View File

@ -32,6 +32,7 @@ motd.txt
*.xml
mcserver_api.lua
cuberite_api.lua
DuplicateDocs.txt
# Ignore the webadmin certs / privkey, so that no-one commits theirs by accident:
webadmin/httpscert.crt

19286
Server/Plugins/APIDump/APIDesc.lua
View File

File diff suppressed because it is too large Load Diff

1433
Server/Plugins/APIDump/Classes/BlockEntities.lua
View File

File diff suppressed because it is too large Load Diff

2591
Server/Plugins/APIDump/Classes/Geometry.lua
View File

File diff suppressed because it is too large Load Diff

635
Server/Plugins/APIDump/Classes/Network.lua
View File

@ -11,8 +11,7 @@ return
{
cNetwork =
{
Desc =
[[
Desc = [[
This is the namespace for high-level network-related operations. Allows plugins to make TCP
connections to the outside world using a callback-based API.</p>
<p>
@ -21,12 +20,139 @@ return
local Server = cNetwork:Listen(1024, ListenCallbacks);
</pre></p>
]],
Functions =
{
Connect =
{
IsStatic = true,
Params =
{
{
Name = "Host",
Type = "string",
},
{
Name = "Port",
Type = "number",
},
{
Name = "LinkCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins establishing a (client) TCP connection to the specified host. Uses the LinkCallbacks table to report progress, success, errors and incoming data. Returns false if it fails immediately (bad port value, bad hostname format), true otherwise. Host can be either an IP address or a hostname.",
},
CreateUDPEndpoint =
{
IsStatic = true,
Params =
{
{
Name = "Port",
Type = "number",
},
{
Name = "UDPCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "cUDPEndpoint",
},
},
Notes = "Creates a UDP endpoint that listens for incoming datagrams on the specified port, and can be used to send or broadcast datagrams. Uses the UDPCallbacks to report incoming datagrams or errors. If the endpoint cannot be created, the OnError callback is called with the error details and the returned endpoint will report IsOpen() == false. The plugin needs to store the returned endpoint object for as long as it needs the UDP port open; if the endpoint is garbage-collected by Lua, the socket will be closed and no more incoming data will be reported.<br>If the Port is zero, the OS chooses an available UDP port for the endpoint; use {{cUDPEndpoint}}:GetPort() to query the port number in such case.",
},
EnumLocalIPAddresses =
{
IsStatic = true,
Returns =
{
{
Type = "table",
},
},
Notes = "Returns all local IP addresses for network interfaces currently available on the machine, as an array-table of strings.",
},
HostnameToIP =
{
IsStatic = true,
Params =
{
{
Name = "Host",
Type = "string",
},
{
Name = "LookupCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins a DNS lookup to find the IP address(es) for the specified host. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad hostname format), true if the lookup started successfully. Host can be either a hostname or an IP address.",
},
IPToHostname =
{
IsStatic = true,
Params =
{
{
Name = "Address",
Type = "string",
},
{
Name = "LookupCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins a reverse-DNS lookup to find out the hostname for the specified IP address. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad address format), true if the lookup started successfully.",
},
Listen =
{
IsStatic = true,
Params =
{
{
Name = "Port",
Type = "number",
},
{
Name = "ListenCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "cServerHandle",
},
},
Notes = "Starts listening on the specified port. Uses the ListenCallbacks to report incoming connections or errors. Returns a {{cServerHandle}} object representing the server. If the listen operation failed, the OnError callback is called with the error details and the returned server handle will report IsListening() == false. The plugin needs to store the server handle object for as long as it needs the server running, if the server handle is garbage-collected by Lua, the listening socket will be closed and all current connections dropped.",
},
},
AdditionalInfo =
{
{
Header = "Using callbacks",
Contents =
[[
Contents = [[
The entire Networking API is callback-based. Whenever an event happens on the network object, a
specific plugin-provided function is called. The callbacks are stored in tables which are passed
to the API functions, each table contains multiple callbacks for the various situations.</p>
@ -146,11 +272,9 @@ local UDPCallbacks =
</pre>
]],
},
{
Header = "Example client connection",
Contents =
[[
Contents = [[
The following example, adapted from the NetworkTest plugin, shows a simple example of a client
connection using the cNetwork API. It connects to www.google.com on port 80 (http) and sends a http
request for the front page. It dumps the received data to the console.</p>
@ -195,11 +319,9 @@ end
</pre>
]],
},
{
Header = "Example server implementation",
Contents =
[[
Contents = [[
The following example, adapted from the NetworkTest plugin, shows a simple example of creating a
server listening on a TCP port using the cNetwork API. The server listens on port 9876 and for
each incoming connection it sends a welcome message and then echoes back whatever the client has
@ -283,41 +405,38 @@ g_Server = nil
</pre>
]],
},
}, -- AdditionalInfo
Functions =
{
Connect = { Params = "Host, Port, LinkCallbacks", Return = "bool", IsStatic = true, Notes = "Begins establishing a (client) TCP connection to the specified host. Uses the LinkCallbacks table to report progress, success, errors and incoming data. Returns false if it fails immediately (bad port value, bad hostname format), true otherwise. Host can be either an IP address or a hostname." },
CreateUDPEndpoint = { Params = "Port, UDPCallbacks", Return = "{{cUDPEndpoint|UDPEndpoint}}", IsStatic = true, Notes = "Creates a UDP endpoint that listens for incoming datagrams on the specified port, and can be used to send or broadcast datagrams. Uses the UDPCallbacks to report incoming datagrams or errors. If the endpoint cannot be created, the OnError callback is called with the error details and the returned endpoint will report IsOpen() == false. The plugin needs to store the returned endpoint object for as long as it needs the UDP port open; if the endpoint is garbage-collected by Lua, the socket will be closed and no more incoming data will be reported.<br>If the Port is zero, the OS chooses an available UDP port for the endpoint; use {{cUDPEndpoint}}:GetPort() to query the port number in such case." },
EnumLocalIPAddresses = { Params = "", Return = "array-table of strings", IsStatic = true, Notes = "Returns all local IP addresses for network interfaces currently available on the machine." },
HostnameToIP = { Params = "Host, LookupCallbacks", Return = "bool", IsStatic = true, Notes = "Begins a DNS lookup to find the IP address(es) for the specified host. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad hostname format), true if the lookup started successfully. Host can be either a hostname or an IP address." },
IPToHostname = { Params = "Address, LookupCallbacks", Return = "bool", IsStatic = true, Notes = "Begins a reverse-DNS lookup to find out the hostname for the specified IP address. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad address format), true if the lookup started successfully." },
Listen = { Params = "Port, ListenCallbacks", Return = "{{cServerHandle|ServerHandle}}", IsStatic = true, Notes = "Starts listening on the specified port. Uses the ListenCallbacks to report incoming connections or errors. Returns a {{cServerHandle}} object representing the server. If the listen operation failed, the OnError callback is called with the error details and the returned server handle will report IsListening() == false. The plugin needs to store the server handle object for as long as it needs the server running, if the server handle is garbage-collected by Lua, the listening socket will be closed and all current connections dropped." },
},
}, -- cNetwork
},
cServerHandle =
{
Desc =
[[
Desc = [[
This class provides an interface for TCP sockets listening for a connection. In order to listen, the
plugin needs to use the {{cNetwork}}:Listen() function to create the listening socket.</p>
<p>
Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin
should keep it referenced in a global variable for as long as it wants the server running.
]],
Functions =
{
Close = { Params = "", Return = "", Notes = "Closes the listening socket. No more connections will be accepted, and all current connections will be closed." },
IsListening = { Params = "", Return = "bool", Notes = "Returns true if the socket is listening." },
Close =
{
Notes = "Closes the listening socket. No more connections will be accepted, and all current connections will be closed.",
},
IsListening =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the socket is listening.",
},
},
}, -- cServerHandle
},
cTCPLink =
{
Desc =
[[
Desc = [[
This class wraps a single TCP connection, that has been established. Plugins can create these by
calling {{cNetwork}}:Connect() to connect to a remote server, or by listening using
{{cNetwork}}:Listen() and accepting incoming connections. The links are callback-based - when an event
@ -332,45 +451,202 @@ g_Server = nil
network. Note that calling Send() before the TLS handshake finishes is supported, but the data is
queued internally and only sent once the TLS handshake is completed.
]],
Functions =
{
Close = { Params = "", Return = "", Notes = "Closes the link forcefully (TCP RST). There's no guarantee that the last sent data is even being delivered. See also the Shutdown() method." },
GetLocalIP = { Params = "", Return = "string", Notes = "Returns the IP address of the local endpoint of the TCP connection." },
GetLocalPort = { Params = "", Return = "number", Notes = "Returns the port of the local endpoint of the TCP connection." },
GetRemoteIP = { Params = "", Return = "string", Notes = "Returns the IP address of the remote endpoint of the TCP connection." },
GetRemotePort = { Params = "", Return = "number", Notes = "Returns the port of the remote endpoint of the TCP connection." },
Send = { Params = "Data", Return = "", Notes = "Sends the data (raw string) to the remote peer. The data is sent asynchronously and there is no report on the success of the send operation, other than the connection being closed or reset by the underlying OS." },
Shutdown = { Params = "", Return = "", Notes = "Shuts the socket down for sending data. Notifies the remote peer that there will be no more data coming from us (TCP FIN). The data that is in flight will still be delivered. The underlying socket will be closed when the remote end shuts down as well, or after a timeout." },
StartTLSClient = { Params = "OwnCert, OwnPrivateKey, OwnPrivateKeyPassword", Return = "true / nil + ErrMsg", Notes = "Starts a TLS handshake on the link, as a client side of the TLS. The Own___ parameters specify the client certificate and its corresponding private key and password; all three parameters are optional and no client certificate is presented to the remote peer if they are not used or all empty. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic." },
StartTLSServer = { Params = "Certificate, PrivateKey, PrivateKeyPassword, StartTLSData", Return = "true / nil + ErrMsg", Notes = "Starts a TLS handshake on the link, as a server side of the TLS. The plugin needs to specify the server certificate and its corresponding private key and password. The StartTLSData can contain data that the link has already reported as received but it should be used as part of the TLS handshake. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic." },
Close =
{
Notes = "Closes the link forcefully (TCP RST). There's no guarantee that the last sent data is even being delivered. See also the Shutdown() method.",
},
GetLocalIP =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the IP address of the local endpoint of the TCP connection.",
},
GetLocalPort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the port of the local endpoint of the TCP connection.",
},
GetRemoteIP =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the IP address of the remote endpoint of the TCP connection.",
},
GetRemotePort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the port of the remote endpoint of the TCP connection.",
},
Send =
{
Params =
{
{
Name = "Data",
Type = "string",
},
},
Notes = "Sends the data (raw string) to the remote peer. The data is sent asynchronously and there is no report on the success of the send operation, other than the connection being closed or reset by the underlying OS.",
},
Shutdown =
{
Notes = "Shuts the socket down for sending data. Notifies the remote peer that there will be no more data coming from us (TCP FIN). The data that is in flight will still be delivered. The underlying socket will be closed when the remote end shuts down as well, or after a timeout.",
},
StartTLSClient =
{
Params =
{
{
Name = "OwnCert",
Type = "string",
},
{
Name = "OwnPrivateKey",
Type = "string",
},
{
Name = "OwnPrivateKeyPassword",
Type = "string",
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessage",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a TLS handshake on the link, as a client side of the TLS. The Own___ parameters specify the client certificate and its corresponding private key and password; all three parameters are optional and no client certificate is presented to the remote peer if they are not used or all empty. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic.",
},
StartTLSServer =
{
Params =
{
{
Name = "Certificate",
Type = "string",
},
{
Name = "PrivateKey",
Type = "string",
},
{
Name = "PrivateKeyPassword",
Type = "string",
},
{
Name = "StartTLSData",
Type = "string",
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessage",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a TLS handshake on the link, as a server side of the TLS. The plugin needs to specify the server certificate and its corresponding private key and password. The StartTLSData can contain data that the link has already reported as received but it should be used as part of the TLS handshake. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic.",
},
},
}, -- cTCPLink
},
cUDPEndpoint =
{
Desc =
[[
Desc = [[
Represents a UDP socket that is listening for incoming datagrams on a UDP port and can send or broadcast datagrams to other peers on the network. Plugins can create an instance of the endpoint by calling {{cNetwork}}:CreateUDPEndpoint(). The endpoints are callback-based - when a datagram is read from the network, the OnRececeivedData() callback is called with details about the datagram. See the additional information in {{cNetwork}} documentation for details.</p>
<p>
Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin should keep this object referenced in a global variable for as long as it wants the endpoint open.
]],
Functions =
{
Close = { Params = "", Return = "", Notes = "Closes the UDP endpoint. No more datagrams will be reported through the callbacks, the UDP port will be closed." },
EnableBroadcasts = { Params = "", Return = "", Notes = "Some OSes need this call before they allow UDP broadcasts on an endpoint." },
GetPort = { Params = "", Return = "number", Notes = "Returns the local port number of the UDP endpoint listening for incoming datagrams. Especially useful if the UDP endpoint was created with auto-assign port (0)." },
IsOpen = { Params = "", Return = "bool", Notes = "Returns true if the UDP endpoint is listening for incoming datagrams." },
Send = { Params = "RawData, RemoteHost, RemotePort", Return = "bool", Notes = "Sends the specified raw data (string) to the specified remote host. The RemoteHost can be either a hostname or an IP address; if it is a hostname, the endpoint will queue a DNS lookup first, if it is an IP address, the send operation is executed immediately. Returns true if there was no immediate error, false on any failure. Note that the return value needn't represent whether the packet was actually sent, only if it was successfully queued." },
Close =
{
Notes = "Closes the UDP endpoint. No more datagrams will be reported through the callbacks, the UDP port will be closed.",
},
EnableBroadcasts =
{
Notes = "Some OSes need this call before they allow UDP broadcasts on an endpoint.",
},
GetPort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the local port number of the UDP endpoint listening for incoming datagrams. Especially useful if the UDP endpoint was created with auto-assign port (0).",
},
IsOpen =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the UDP endpoint is listening for incoming datagrams.",
},
Send =
{
Params =
{
{
Name = "RawData",
Type = "string",
},
{
Name = "RemoteHost",
Type = "string",
},
{
Name = "RemotePort",
Type = "number",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Sends the specified raw data (string) to the specified remote host. The RemoteHost can be either a hostname or an IP address; if it is a hostname, the endpoint will queue a DNS lookup first, if it is an IP address, the send operation is executed immediately. Returns true if there was no immediate error, false on any failure. Note that the return value needn't represent whether the packet was actually sent, only if it was successfully queued.",
},
},
}, -- cUDPEndpoint
},
cUrlClient =
{
Desc =
[[
Desc = [[
Implements high-level asynchronous access to URLs, such as downloading webpages over HTTP(S).</p>
<p>
Note that unlike other languages' URL access libraries, this class implements asynchronous requests.
@ -391,13 +667,233 @@ g_Server = nil
POST and PUT requests), and an Options parameter specifying additional options specific to the protocol
used.
]],
Functions =
{
Delete =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessagge",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP DELETE request. Alias for Request(\"DELETE\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Get =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP GET request. Alias for Request(\"GET\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Post =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP POST request. Alias for Request(\"POST\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Put =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP PUT request. Alias for Request(\"PUT\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Request =
{
IsStatic = true,
Params =
{
{
Name = "Method",
Type = "string",
},
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a request with the specified Method. Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
},
AdditionalInfo =
{
{
Header = "Simple Callback",
Contents =
[[
Contents = [[
When you don't need fine control for receiving the requests and are interested only in the result,
you can use the simple callback approach. Pass a single function as the Callback parameter, the
function will get called when the response is fully processed, either with the body of the response,
@ -418,8 +914,7 @@ cUrlClient:Get(url,
},
{
Header = "Callback Table",
Contents =
[[
Contents = [[
To provide complete control over the request and response handling, Cuberite allows plugins to pass
a table of callbacks as the Callback parameter. Then the respective functions are called for their
respective events during the lifetime of the request and response. This way it is possible to
@ -504,8 +999,7 @@ end
},
{
Header = "Options",
Contents =
[[
Contents = [[
The requests support the following options, specified in the optional Options table parameter:
<table>
<tr><th>Option name</th><th>Description</th></tr>
@ -527,18 +1021,5 @@ end
]],
},
},
Functions =
{
Delete = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP DELETE request. Alias for Request(\"DELETE\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Get = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP GET request. Alias for Request(\"GET\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Post = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP POST request. Alias for Request(\"POST\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Put = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP PUT request. Alias for Request(\"PUT\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Request = { Params = "Method, URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a request with the specified Method. Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
},
}, -- cUrlClient
},
}

1082
Server/Plugins/APIDump/Classes/Plugins.lua
View File

File diff suppressed because it is too large Load Diff

454
Server/Plugins/APIDump/Classes/Projectiles.lua
View File

@ -7,24 +7,115 @@ return
]],
Functions =
{
CanPickup = { Params = "{{cPlayer|Player}}", Return = "bool", Notes = "Returns true if the specified player can pick the arrow when it's on the ground" },
GetBlockHit = { Params = "", Returns = "{{Vector3i}}", Desc = "Gets the block arrow is in" },
GetDamageCoeff = { Params = "", Return = "number", Notes = "Returns the damage coefficient stored within the arrow. The damage dealt by this arrow is multiplied by this coeff" },
GetPickupState = { Params = "", Return = "PickupState", Notes = "Returns the pickup state (one of the psXXX constants, above)" },
IsCritical = { Params = "", Return = "bool", Notes = "Returns true if the arrow should deal critical damage. Based on the bow charge when the arrow was shot." },
SetDamageCoeff = { Params = "number", Return = "", Notes = "Sets the damage coefficient. The damage dealt by this arrow is multiplied by this coeff" },
SetIsCritical = { Params = "bool", Return = "", Notes = "Sets the IsCritical flag on the arrow. Critical arrow deal additional damage" },
SetPickupState = { Params = "PickupState", Return = "", Notes = "Sets the pickup state (one of the psXXX constants, above)" },
CanPickup =
{
Params =
{
{
Name = "Player",
Type = "cPlayer",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the specified player can pick the arrow when it's on the ground",
},
GetBlockHit =
{
Desc = "Gets the block arrow is in",
Returns =
{
{
Type = "Vector3i",
},
},
},
GetDamageCoeff =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the damage coefficient stored within the arrow. The damage dealt by this arrow is multiplied by this coeff",
},
GetPickupState =
{
Returns =
{
{
Type = "cArrowEntity#ePickupState",
},
},
Notes = "Returns the pickup state (one of the psXXX constants, above)",
},
IsCritical =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the arrow should deal critical damage. Based on the bow charge when the arrow was shot.",
},
SetDamageCoeff =
{
Params =
{
{
Name = "DamageCoeff",
Type = "number",
},
},
Notes = "Sets the damage coefficient. The damage dealt by this arrow is multiplied by this coeff",
},
SetIsCritical =
{
Params =
{
{
Name = "IsCritical",
Type = "boolean",
},
},
Notes = "Sets the IsCritical flag on the arrow. Critical arrow deal additional damage",
},
SetPickupState =
{
Params =
{
{
Name = "PickupState",
Type = "cArrowEntity#ePickupState",
},
},
Notes = "Sets the pickup state (one of the psXXX constants, above)",
},
},
Constants =
{
psInCreative = { Notes = "The arrow can be picked up only by players in creative gamemode" },
psInSurvivalOrCreative = { Notes = "The arrow can be picked up by players in survival or creative gamemode" },
psNoPickup = { Notes = "The arrow cannot be picked up at all" },
psInCreative =
{
Notes = "The arrow can be picked up only by players in creative gamemode",
},
psInSurvivalOrCreative =
{
Notes = "The arrow can be picked up by players in survival or creative gamemode",
},
psNoPickup =
{
Notes = "The arrow cannot be picked up at all",
},
},
ConstantGroups =
{
PickupState =
ePickupState =
{
Include = "ps.*",
TextBefore = [[
@ -34,9 +125,7 @@ return
},
},
Inherits = "cProjectileEntity",
}, -- cArrowEntity
},
cExpBottleEntity =
{
Desc = [[
@ -44,146 +133,325 @@ return
]],
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cExpBottleEntity
},
cFireChargeEntity =
{
Desc = [[
Represents a fire charge that has been shot by a Blaze or a {{cDispenserEntity|Dispenser}}. A subclass
of the {{cProjectileEntity}}.
]],
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cFireChargeEntity
},
cFireworkEntity =
{
Desc = [[
Represents a firework rocket.
]],
Functions =
Functions =
{
GetItem =
{
GetItem = { Params = "", Return = "{{cItem}}", Notes = "Returns the item that has been used to create the firework rocket. The item's m_FireworkItem member contains all the firework-related data." },
GetTicksToExplosion = { Params = "", Return = "number", Notes = "Returns the number of ticks left until the firework explodes." },
SetItem = { Params = "{{cItem}}", Return = "", Notes = "Sets a new item to be used for the firework." },
SetTicksToExplosion = { Params = "NumTicks", Return = "", Notes = "Sets the number of ticks left until the firework explodes." },
Returns =
{
{
Type = "cItem",
},
},
Notes = "Returns the item that has been used to create the firework rocket. The item's m_FireworkItem member contains all the firework-related data.",
},
GetTicksToExplosion =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the number of ticks left until the firework explodes.",
},
SetItem =
{
Params =
{
{
Name = "FireworkItem",
Type = "cItem",
},
},
Notes = "Sets a new item to be used for the firework.",
},
SetTicksToExplosion =
{
Params =
{
{
Name = "NumTicks",
Type = "number",
},
},
Notes = "Sets the number of ticks left until the firework explodes.",
},
},
Inherits = "cProjectileEntity",
}, -- cFireworkEntity
cFloater =
{
Desc = "",
Functions = {},
Inherits = "cProjectileEntity",
}, -- cFloater
},
cGhastFireballEntity =
{
Desc = "",
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cGhastFireballEntity
},
cProjectileEntity =
{
Desc = "Base class for all projectiles, such as arrows and fireballs.",
Functions =
{
GetCreator = { Params = "", Return = "{{cEntity}} descendant", Notes = "Returns the entity who created this projectile. May return nil." },
GetCreatorName = { Params = "", Return = "string", Notes = "Returns the name of the player that created the projectile. Will be empty for non-player creators" },
GetCreatorUniqueID = { Params = "", Return = "number", Notes = "Returns the unique ID of the entity who created this projectile, or {{cEntity#NO_ID|cEntity.NO_ID}} if the projectile wasn't created by an entity." },
GetMCAClassName = { Params = "", Return = "string", Notes = "Returns the string that identifies the projectile type (class name) in MCA files" },
GetProjectileKind = { Params = "", Return = "ProjectileKind", Notes = "Returns the kind of this projectile (pkXXX constant)" },
IsInGround = { Params = "", Return = "bool", Notes = "Returns true if this projectile has hit the ground." },
GetCreator =
{
Returns =
{
{
Type = "cEntity",
},
},
Notes = "Returns the entity who created this projectile. May return nil.",
},
GetCreatorName =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the name of the player that created the projectile. Will be empty for non-player creators",
},
GetCreatorUniqueID =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the unique ID of the entity who created this projectile, or {{cEntity#INVALID_ID|cEntity.INVALID_ID}} if the projectile wasn't created by an entity.",
},
GetMCAClassName =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string that identifies the projectile type (class name) in MCA files",
},
GetProjectileKind =
{
Returns =
{
{
Type = "cProjectileEntity#eKind",
},
},
Notes = "Returns the kind of this projectile (pkXXX constant)",
},
IsInGround =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if this projectile has hit the ground.",
},
},
Constants =
{
pkArrow = { Notes = "The projectile is an {{cArrowEntity|arrow}}" },
pkEgg = { Notes = "The projectile is a {{cThrownEggEntity|thrown egg}}" },
pkEnderPearl = { Notes = "The projectile is a {{cThrownEnderPearlEntity|thrown enderpearl}}" },
pkExpBottle = { Notes = "The projectile is a {{cExpBottleEntity|thrown exp bottle}}" },
pkFireCharge = { Notes = "The projectile is a {{cFireChargeEntity|fire charge}}" },
pkFirework = { Notes = "The projectile is a (flying) {{cFireworkEntity|firework}}" },
pkFishingFloat = { Notes = "The projectile is a {{cFloater|fishing float}}" },
pkGhastFireball = { Notes = "The projectile is a {{cGhastFireballEntity|ghast fireball}}" },
pkSnowball = { Notes = "The projectile is a {{cThrownSnowballEntity|thrown snowball}}" },
pkSplashPotion = { Notes = "The projectile is a {{cSplashPotionEntity|thrown splash potion}}" },
pkWitherSkull = { Notes = "The projectile is a {{cWitherSkullEntity|wither skull}}" },
pkArrow =
{
Notes = "The projectile is an {{cArrowEntity|arrow}}",
},
pkEgg =
{
Notes = "The projectile is a {{cThrownEggEntity|thrown egg}}",
},
pkEnderPearl =
{
Notes = "The projectile is a {{cThrownEnderPearlEntity|thrown enderpearl}}",
},
pkExpBottle =
{
Notes = "The projectile is a {{cExpBottleEntity|thrown exp bottle}}",
},
pkFireCharge =
{
Notes = "The projectile is a {{cFireChargeEntity|fire charge}}",
},
pkFirework =
{
Notes = "The projectile is a (flying) {{cFireworkEntity|firework}}",
},
pkFishingFloat =
{
Notes = "The projectile is a {{cFloater|fishing float}}",
},
pkGhastFireball =
{
Notes = "The projectile is a {{cGhastFireballEntity|ghast fireball}}",
},
pkSnowball =
{
Notes = "The projectile is a {{cThrownSnowballEntity|thrown snowball}}",
},
pkSplashPotion =
{
Notes = "The projectile is a {{cSplashPotionEntity|thrown splash potion}}",
},
pkWitherSkull =
{
Notes = "The projectile is a {{cWitherSkullEntity|wither skull}}",
},
},
ConstantGroups =
{
ProjectileKind =
eKind =
{
Include = "pk.*",
TextBefore = "The following constants are used to distinguish between the different projectile kinds:",
},
},
Inherits = "cEntity",
}, -- cProjectileEntity
},
cSplashPotionEntity =
{
Desc = [[
Represents a thrown splash potion.
]],
Functions =
Functions =
{
GetEntityEffect =
{
GetEntityEffect = { Params = "", Return = "{{cEntityEffect}}", Notes = "Returns the entity effect in this potion" },
GetEntityEffectType = { Params = "", Return = "{{cEntityEffect|Entity effect type}}", Notes = "Returns the effect type of this potion" },
GetPotionColor = { Params = "", Return = "number", Notes = "Returns the color index of the particles emitted by this potion" },
GetItem = { Params = "", Return = "{{cItem}}", Notes = "Gets the potion item that was thrown." },
SetEntityEffect = { Params = "{{cEntityEffect}}", Return = "", Notes = "Sets the entity effect for this potion" },
SetEntityEffectType = { Params = "{{cEntityEffect|Entity effect type}}", Return = "", Notes = "Sets the effect type of this potion" },
SetPotionColor = { Params = "number", Return = "", Notes = "Sets the color index of the particles for this potion" },
Returns =
{
{
Type = "cEntityEffect",
},
},
Notes = "Returns the entity effect in this potion",
},
GetEntityEffectType =
{
Returns =
{
{
Type = "cEntityEffect",
},
},
Notes = "Returns the effect type of this potion",
},
GetItem =
{
Returns =
{
{
Type = "cItem",
},
},
Notes = "Gets the potion item that was thrown.",
},
GetPotionColor =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the color index of the particles emitted by this potion",
},
SetEntityEffect =
{
Params =
{
{
Name = "EntityEffect",
Type = "cEntityEffect",
},
},
Notes = "Sets the entity effect for this potion",
},
SetEntityEffectType =
{
Params =
{
{
Name = "EntityEffectType",
Type = "cEntityEffect#eType",
},
},
Notes = "Sets the effect type of this potion",
},
SetPotionColor =
{
Params =
{
{
Name = "PotionColor",
Type = "number",
},
},
Notes = "Sets the color index of the particles for this potion",
},
},
Inherits = "cProjectileEntity",
}, -- cSplashPotionEntity
},
cThrownEggEntity =
{
Desc = [[
Represents a thrown egg.
]],
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cThrownEggEntity
},
cThrownEnderPearlEntity =
{
Desc = "Represents a thrown ender pearl.",
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cThrownEnderPearlEntity
},
cThrownSnowballEntity =
{
Desc = "Represents a thrown snowball.",
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cThrownSnowballEntity
},
cWitherSkullEntity =
{
Desc = "Represents a wither skull being shot.",
Functions = {},
Functions =
{
},
Inherits = "cProjectileEntity",
}, -- cWitherSkullEntity
},
}

229
Server/Plugins/APIDump/Classes/WebAdmin.lua
View File

@ -5,31 +5,165 @@ return
Desc = "",
Functions =
{
AddWebTab = { Params = "Title, UrlPath, HandlerFn", Return = "", IsStatic = true, Notes = "Adds a new web tab to webadmin. The tab uses \"Title\" as its display string and is identified in the URL using the UrlPath (https://server.domain.com/webadmin/{PluginName}/{UrlPath}). The HandlerFn is the callback function that is called when the admin accesses the page, it has the following signature:<br/><pre class=\"prettyprint lang-lua\">function ({{a_Request|HTTPRequest}}, a_UrlPath)<br/> return Content, ContentType<br/>end</pre> URLPath must not contain a '/', the recommendation is to use only 7-bit-clean ASCII character set." },
GetAllWebTabs = { Params = "", Return = "array-table", IsStatic = true, Notes = "Returns an array-table with each item describing a web tab, for all web tabs registered in the WebAdmin, for all plugins. The returned table has the following format:<br/><pre class=\"prettyprint lang-lua\">{<br/> {<br/> PluginName = \"Plugin's API name\",<br/> UrlPath = \"UrlPath given to AddWebTab\",<br/> Title = \"Title given to AddWebTab\",<br/> },<br/> ...<br/>}"},
GetBaseURL = { Params = "URL", Return = "string", IsStatic = true, Notes = "Returns the string that is the path of the base webadmin (\"../../../webadmin\") relative to the given URL." },
GetContentTypeFromFileExt = { Params = "FileExt", Return = "string", IsStatic = true, Notes = "Returns the content-type that should be used for files with the specified extension (without the dot), such as \"text/plain\" for the \"txt\" extension. If the extension is not known, returns an empty string." },
GetHTMLEscapedString = { Params = "string", Return = "string", IsStatic = true, Notes = "Gets the HTML-escaped representation of a requested string. This is useful for user input and game data that is not guaranteed to be escaped already." },
GetPage = { Params = "{{Request|HTTPRequest}}", Return = "table", IsStatic = true, Notes = "Returns the (inner HTML) page contents for the specified request. Calls the appropriate WebTab handler registered via AddWebTab() and returns the information from that plugin wrapped in a table with the following structure:<br/><pre class=\"prettyprint lang-lua\">{<br/> Content = \"\", -- Content returned by the plugin<br/> ContentType = \"\", -- Content type returned by the plugin, or \"text/html\" if none returned<br/> UrlPath = \"\", -- UrlPath decoded from the request<br/> TabTitle = \"\", -- Title of the tab that handled the request, as given to AddWebTab()<br/> PluginName = \"\", -- API name of the plugin that handled the request<br/> PluginFolder = \"\", -- Folder name (= display name) of the plugin that handled the request<br/>}</pre>This function is mainly used in the webadmin template file." },
GetPorts = { Params = "", Return = "string", Notes = "Returns a comma-separated list of ports on which the webadmin is configured to listen. Note that this list does include ports that may currently be unavailable (another server was already listening on them prior to launching Cuberite)." },
GetURLEncodedString = { Params = "string", Return = "string", IsStatic = true, Notes = "Returns the string given to it escaped by URL encoding, which makes the string suitable for transmission in an URL. Invalid characters are turned into \"%xy\" values." },
Reload = { Params = "", Return = "", Notes = "Reloads the webadmin's config - the allowed logins, the template script and the login page. Note that reloading will not change the \"enabled\" state of the server, and it will not update listening ports. Existing WebTabs will be kept registered even after the reload." },
AddWebTab =
{
IsStatic = true,
Params =
{
{
Name = "Title",
Type = "string",
},
{
Name = "UrlPath",
Type = "string",
},
{
Name = "HandlerFn",
Type = "function",
},
},
Notes = "Adds a new web tab to webadmin. The tab uses \"Title\" as its display string and is identified in the URL using the UrlPath (https://server.domain.com/webadmin/{PluginName}/{UrlPath}). The HandlerFn is the callback function that is called when the admin accesses the page, it has the following signature:<br/><pre class=\"prettyprint lang-lua\">function ({{a_Request|HTTPRequest}}, a_UrlPath)<br/> return Content, ContentType<br/>end</pre> URLPath must not contain a '/', the recommendation is to use only 7-bit-clean ASCII character set.",
},
GetAllWebTabs =
{
IsStatic = true,
Returns =
{
{
Type = "table",
},
},
Notes = "Returns an array-table with each item describing a web tab, for all web tabs registered in the WebAdmin, for all plugins. The returned table has the following format:<br/><pre class=\"prettyprint lang-lua\">{<br/> {<br/> PluginName = \"Plugin's API name\",<br/> UrlPath = \"UrlPath given to AddWebTab\",<br/> Title = \"Title given to AddWebTab\",<br/> },<br/> ...<br/>}",
},
GetBaseURL =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string that is the path of the base webadmin (\"../../../webadmin\") relative to the given URL.",
},
GetContentTypeFromFileExt =
{
IsStatic = true,
Params =
{
{
Name = "FileExt",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the content-type that should be used for files with the specified extension (without the dot), such as \"text/plain\" for the \"txt\" extension. If the extension is not known, returns an empty string.",
},
GetHTMLEscapedString =
{
IsStatic = true,
Params =
{
{
Name = "Input",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Gets the HTML-escaped representation of a requested string. This is useful for user input and game data that is not guaranteed to be escaped already.",
},
GetPage =
{
IsStatic = true,
Params =
{
{
Name = "HTTPRequest",
Type = "Request",
},
},
Returns =
{
{
Type = "table",
},
},
Notes = "Returns the (inner HTML) page contents for the specified request. Calls the appropriate WebTab handler registered via AddWebTab() and returns the information from that plugin wrapped in a table with the following structure:<br/><pre class=\"prettyprint lang-lua\">{<br/> Content = \"\", -- Content returned by the plugin<br/> ContentType = \"\", -- Content type returned by the plugin, or \"text/html\" if none returned<br/> UrlPath = \"\", -- UrlPath decoded from the request<br/> TabTitle = \"\", -- Title of the tab that handled the request, as given to AddWebTab()<br/> PluginName = \"\", -- API name of the plugin that handled the request<br/> PluginFolder = \"\", -- Folder name (= display name) of the plugin that handled the request<br/>}</pre>This function is mainly used in the webadmin template file.",
},
GetPorts =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns a comma-separated list of ports on which the webadmin is configured to listen. Note that this list does include ports that may currently be unavailable (another server was already listening on them prior to launching Cuberite).",
},
GetURLEncodedString =
{
IsStatic = true,
Params =
{
{
Name = "Input",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string given to it escaped by URL encoding, which makes the string suitable for transmission in an URL. Invalid characters are turned into \"%xy\" values.",
},
Reload =
{
Notes = "Reloads the webadmin's config - the allowed logins, the template script and the login page. Note that reloading will not change the \"enabled\" state of the server, and it will not update listening ports. Existing WebTabs will be kept registered even after the reload.",
},
},
}, -- cWebAdmin
},
HTTPFormData =
{
Desc = "This class stores data for one form element for a {{HTTPRequest|HTTP request}}.",
Variables =
{
Name = { Type = "string", Notes = "Name of the form element" },
Type = { Type = "string", Notes = "Type of the data (usually empty)" },
Value = { Type = "string", Notes = "Value of the form element. Contains the raw data as sent by the browser." },
Name =
{
Type = "string",
Notes = "Name of the form element",
},
Type =
{
Type = "string",
Notes = "Type of the data (usually empty)",
},
Value =
{
Type = "string",
Notes = "Value of the form element. Contains the raw data as sent by the browser.",
},
},
}, -- HTTPFormData
},
HTTPRequest =
{
Desc = [[
@ -39,32 +173,55 @@ return
]],
Constants =
{
FormData = { Notes = "Array-table of {{HTTPFormData}}, contains the values of individual form elements submitted by the client" },
Params = { Notes = "Map-table of parameters given to the request in the URL (?param=value); if a form uses GET method, this is the same as FormData. For each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value." },
PostParams = { Notes = "Map-table of data posted through a FORM - either a GET or POST method. Logically the same as FormData, but in a map-table format (for each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value)." },
Params =
{
Notes = "Map-table of parameters given to the request in the URL (?param=value); if a form uses GET method, this is the same as FormData. For each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value.",
},
FormData =
{
Notes = "Array-table of {{HTTPFormData}}, contains the values of individual form elements submitted by the client",
},
PostParams =
{
Notes = "Map-table of data posted through a FORM - either a GET or POST method. Logically the same as FormData, but in a map-table format (for each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value).",
},
},
Variables =
{
Method = { Type = "string", Notes = "The HTTP method used to make the request. Usually GET or POST." },
Path = { Type = "string", Notes = "The Path part of the URL (excluding the parameters)" },
URL = { Type = "string", Notes = "The entire URL used for the request." },
Username = { Type = "string", Notes = "Name of the logged-in user." },
Method =
{
Type = "string",
Notes = "The HTTP method used to make the request. Usually GET or POST.",
},
Path =
{
Type = "string",
Notes = "The Path part of the URL (excluding the parameters)",
},
URL =
{
Type = "string",
Notes = "The entire URL used for the request.",
},
Username =
{
Type = "string",
Notes = "Name of the logged-in user.",
},
},
}, -- HTTPRequest
},
HTTPTemplateRequest =
{
Desc = [[This class is used only in the WebAdmin template script as the parameter to the function that provides the template.
Desc = [[
This class is used only in the WebAdmin template script as the parameter to the function that provides the template.
]],
Variables =
{
Request = { Type = "HTTPRequest", Notes = "The request for which the template is being built." },
Request =
{
Type = "HTTPRequest",
Notes = "The request for which the template is being built.",
},
},
}, -- HTTPTemplateRequest
},
}

142
Server/Plugins/APIDump/main_APIDump.lua
View File

@ -36,6 +36,16 @@ local function LoadAPIFiles(a_Folder, a_DstTable)
break
end
for k, cls in pairs(Tables) do
if (a_DstTable[k]) then
-- The class is documented in two files, warn and store into a file (so that CIs can mark build as failure):
LOGWARNING(string.format(
"APIDump warning: class %s is documented at two places, the documentation in file %s will overwrite the previously loaded one!",
k, FileName
))
local f = io.open("DuplicateDocs.txt", "a")
f:write(k, "\t", FileName)
f:close()
end
a_DstTable[k] = cls;
end
end -- if (TablesFn)
@ -146,6 +156,12 @@ local function CreateAPITables()
end
end
-- Remove the built-in Lua libraries:
API.debug = nil
API.io = nil
API.string = nil
API.table = nil
return API, Globals;
end
@ -505,8 +521,8 @@ local function ReadDescriptions(a_API, a_Desc)
local DoxyFunctions = {}; -- This will contain all the API functions together with their documentation
local function AddFunction(a_Name, a_Params, a_Return, a_IsStatic, a_Notes)
table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Return = a_Return, IsStatic = a_IsStatic, Notes = a_Notes});
local function AddFunction(a_Name, a_Params, a_Returns, a_IsStatic, a_Notes)
table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Returns = a_Returns, IsStatic = a_IsStatic, Notes = a_Notes});
end
if (APIDesc.Functions ~= nil) then
@ -524,11 +540,11 @@ local function ReadDescriptions(a_API, a_Desc)
-- Description is available
if (FnDesc[1] == nil) then
-- Single function definition
AddFunction(func.Name, FnDesc.Params, FnDesc.Return, FnDesc.IsStatic, FnDesc.Notes);
AddFunction(func.Name, FnDesc.Params, FnDesc.Returns, FnDesc.IsStatic, FnDesc.Notes);
else
-- Multiple function overloads
for _, desc in ipairs(FnDesc) do
AddFunction(func.Name, desc.Params, desc.Return, desc.IsStatic, desc.Notes);
AddFunction(func.Name, desc.Params, desc.Returns, desc.IsStatic, desc.Notes);
end -- for k, desc - FnDesc[]
end
FnDesc.IsExported = true;
@ -676,13 +692,6 @@ local function ReadDescriptions(a_API, a_Desc)
-- Sort the functions (they may have been renamed):
table.sort(cls.Functions,
function(f1, f2)
if (f1.Name == f2.Name) then
-- Same name, either comparing the same function to itself, or two overloads, in which case compare the params
if ((f1.Params == nil) or (f2.Params == nil)) then
return 0;
end
return (f1.Params < f2.Params);
end
return (f1.Name < f2.Name);
end
);
@ -761,7 +770,91 @@ end
local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
--- Returns a HTML string describing the (parameter) type, linking to the type's documentation, if available
-- a_Type is the string containing the type (such as "cPlugin" or "number"), or nil
-- a_API is the complete API description (used for searching the classnames)
local function LinkifyType(a_Type, a_API)
-- Check params:
assert(type(a_Type) == "string")
assert(type(a_API) == "table")
-- If the type is a known class, return a direct link to it:
if (a_API[a_Type]) then
return "<a href=\"" .. a_Type .. ".html\">" .. a_Type .. "</a>"
end
-- If the type has a hash sign, it's a child enum of a class:
local idxColon = a_Type:find("#")
if (idxColon) then
local classType = a_Type:sub(1, idxColon - 1)
if (a_API[classType]) then
local enumType = a_Type:sub(idxColon + 1)
return "<a href=\"" .. classType .. ".html#" .. enumType .. "\">" .. enumType .. "</a>"
end
end
-- If the type is a ConstantGroup within the Globals, it's a global enum:
if ((a_API.Globals.ConstantGroups or {})[a_Type]) then
return "<a href=\"Globals.html#" .. a_Type .. "\">" .. a_Type .. "</a>"
end
-- Unknown or built-in type, output just text:
return a_Type
end
--- Returns an HTML string describing all function parameters (or return values)
-- a_FnParams is an array-table or string description of the parameters
-- a_ClassName is the name of the class for which the function is being documented (for Linkification)
-- a_API is the complete API description (for cross-type linkification)
local function CreateFunctionParamsDescription(a_FnParams, a_ClassName, a_API)
local pt = type(a_FnParams)
assert((pt == "string") or (pt == "table"))
assert(type(a_ClassName) == "string")
assert(type(a_API) == "table")
-- If the params description is a string (old format), just linkify it:
if (pt == "string") then
return LinkifyString(a_FnParams, a_ClassName)
end
-- If the params description is an empty table, give no description at all:
if not(a_FnParams[1]) then
return ""
end
-- The params description is a table, output the full desc:
local res = {"<table border=0 cellspacing=0>"}
local idx = 2
for _, param in ipairs(a_FnParams) do
res[idx] = "<tr><td>"
res[idx + 1] = param.Name or ""
res[idx + 2] = "</td><td><i>"
res[idx + 3] = LinkifyType(param.Type, a_API)
res[idx + 4] = "</i></td></tr>"
idx = idx + 5
end
res[idx] = "</tr></table>"
return table.concat(res)
end
--- Writes an HTML file containing the class API description for the given class
-- a_ClassAPI is the API description of the class to output
-- a_ClassMenu is the HTML string containing the code for the menu sidebar
-- a_API is the complete API (for cross-type linkification)
local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
-- Check params:
assert(type(a_ClassAPI) == "table")
assert(type(a_ClassMenu) == "string")
assert(type(a_API) == "table")
local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w");
if (cf == nil) then
LOGINFO("Cannot write HTML API for class " .. a_ClassAPI.Name .. ": " .. err)
@ -770,11 +863,12 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
-- Writes a table containing all functions in the specified list, with an optional "inherited from" header when a_InheritedName is valid
local function WriteFunctions(a_Functions, a_InheritedName)
if (#a_Functions == 0) then
if not(a_Functions[1]) then
-- No functions to write
return;
end
if (a_InheritedName ~= nil) then
if (a_InheritedName) then
cf:write("<h2>Functions inherited from ", a_InheritedName, "</h2>\n");
end
cf:write("<table>\n<tr><th>Name</th><th>Parameters</th><th>Return value</th><th>Notes</th></tr>\n");
@ -789,8 +883,8 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu)
TableOverloadedFunctions[func.Name] = (TableOverloadedFunctions[func.Name] or 0) + 1
-- Add the anchor names as a title
cf:write("<tr><td id=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\" title=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\">", func.Name, "</td>\n");
cf:write("<td>", LinkifyString(func.Params or "", (a_InheritedName or a_ClassAPI.Name)), "</td>\n");
cf:write("<td>", LinkifyString(func.Return or "", (a_InheritedName or a_ClassAPI.Name)), "</td>\n");
cf:write("<td>", CreateFunctionParamsDescription(func.Params or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n");
cf:write("<td>", CreateFunctionParamsDescription(func.Returns or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n");
cf:write("<td>", StaticClause .. LinkifyString(func.Notes or "<i>(undocumented)</i>", (a_InheritedName or a_ClassAPI.Name)), "</td></tr>\n");
end
cf:write("</table>\n");
@ -1032,7 +1126,7 @@ local function WriteClasses(f, a_API, a_ClassMenu)
]]);
for _, cls in ipairs(a_API) do
f:write("<li><a href=\"", cls.Name, ".html\">", cls.Name, "</a></li>\n");
WriteHtmlClass(cls, a_ClassMenu);
WriteHtmlClass(cls, a_ClassMenu, a_API);
end
f:write([[
</ul></p>
@ -1452,6 +1546,7 @@ local function WriteZBSMethods(f, a_Methods)
f:write("\t\t\t[\"", func.Name, "\"] =\n")
f:write("\t\t\t{\n")
f:write("\t\t\t\ttype = \"method\",\n")
-- No way to indicate multiple signatures to ZBS, so don't output any params at all
if ((func.Notes ~= nil) and (func.Notes ~= "")) then
f:write("\t\t\t\tdescription = [[", CleanUpDescription(func.Notes or ""), " ]],\n")
end
@ -1648,14 +1743,10 @@ local function PrepareApi()
-- Load the API descriptions from the Classes and Hooks subfolders:
-- This needs to be done each time the command is invoked because the export modifies the tables' contents
local apiDesc = dofile(g_PluginFolder .. "/APIDesc.lua")
if (apiDesc.Classes == nil) then
apiDesc.Classes = {};
end
if (apiDesc.Hooks == nil) then
apiDesc.Hooks = {};
end
LoadAPIFiles("/Classes/", apiDesc.Classes);
LoadAPIFiles("/Hooks/", apiDesc.Hooks);
apiDesc.Classes = apiDesc.Classes or {}
apiDesc.Hooks = apiDesc.Hooks or {}
LoadAPIFiles("/Classes/", apiDesc.Classes)
LoadAPIFiles("/Hooks/", apiDesc.Hooks)
-- Reset the stats:
g_TrackedPages = {}; -- List of tracked pages, to be checked later whether they exist. Each item is an array of referring pagenames.
@ -1689,6 +1780,7 @@ local function PrepareApi()
-- Add Globals into the API:
Globals.Name = "Globals";
table.insert(API, Globals);
API.Globals = Globals
-- Read in the descriptions:
LOG("Reading descriptions...");

4
src/Item.h
View File

@ -197,8 +197,8 @@ public:
/** Returns the enchantability of the item. When the item hasn't a enchantability, it will returns 0 */
int GetEnchantability(); // tolua_export
/** Enchants the item using the specified number of XP levels.
Returns true if item enchanted, false if not. */
/** Randomly enchants the item using the specified number of XP levels.
Returns true if the item was enchanted, false if not (not enchantable / too many enchantments already). */
bool EnchantByXPLevels(int a_NumXPLevels); // tolua_export
// tolua_begin

2
src/Mobs/Monster.h
View File

@ -62,7 +62,7 @@ public:
virtual void HandleFalling(void) override;
/** Engage pathfinder and tell it to calculate a path to a given position, and move the mobile accordingly
/** Engage pathfinder and tell it to calculate a path to a given position, and move the mob accordingly
Currently, the mob will only start moving to a new position after the position it is currently going to is reached. */
virtual void MoveToPosition(const Vector3d & a_Position); // tolua_export

3
src/World.h
View File

@ -477,7 +477,8 @@ public:
bool DigBlock (int a_X, int a_Y, int a_Z);
virtual void SendBlockTo(int a_X, int a_Y, int a_Z, cPlayer * a_Player) override;
/** Set default spawn at the given coordinates. */
/** Set default spawn at the given coordinates.
Returns false if the new spawn couldn't be stored in the INI file. */
bool SetSpawn(double a_X, double a_Y, double a_Z);
double GetSpawnX(void) const { return m_SpawnX; }