From 7b3646a012e4cc330c17328e13b31fec6a3280a8 Mon Sep 17 00:00:00 2001 From: KliPPy Date: Sat, 9 Dec 2017 00:22:43 +0100 Subject: [PATCH] Update include files documentation (#360) * Update include files documentation * Fix inconcistencies with spaces/tabs, some changes * Update fun, nvault, vector * Update sqlx.inc --- plugins/include/float.inc | 311 +++++++++++++--- plugins/include/fun.inc | 273 ++++++++++++-- plugins/include/nvault.inc | 122 ++++++- plugins/include/sockets.inc | 4 + plugins/include/sqlx.inc | 404 +++++++++++++++------ plugins/include/vector.inc | 88 ++++- plugins/include/xs.inc | 687 ++++++++++++++++++++++++++++-------- 7 files changed, 1508 insertions(+), 381 deletions(-) diff --git a/plugins/include/float.inc b/plugins/include/float.inc index 35b65aea..a8c9ee06 100755 --- a/plugins/include/float.inc +++ b/plugins/include/float.inc @@ -13,7 +13,11 @@ #endif #define _float_included -/* Different methods of rounding */ +#pragma rational Float + +/** + * Different methods of rounding + */ enum floatround_method { floatround_round = 0, floatround_floor, @@ -21,19 +25,242 @@ enum floatround_method { floatround_tozero }; +/** + * Different units of measurement for angles + */ enum anglemode { radian = 0, degrees, grades }; -/* Convert an integer into a floating point value */ +/** + * Converts an integer into a floating point value. + * + * @param value Value to be converted + * + * @return Converted value + */ native Float:float(value); -/* Convert a string into a floating point value */ +/** + * Converts a string into a floating point value. + * + * @param string Input string to be converted + * + * @return Converted value + */ native Float:floatstr(const string[]); -/* Multiple two floats together */ +/** + * Returns the fractional part of a floating point value + * + * @param string Floating point value to get the fractional part from + * + * @return The fractional part + */ +native Float:floatfract(Float:value); + +/** + * Rounds a floating point value to an integer value + * + * @note For the list of available rounding methods look at + * floatround_method enumeration. + * + * @param value Floating point value to be rounded + * @param method Rounding method + * + * @return Converted value + */ +native floatround(Float:value, floatround_method:method=floatround_round); + +/** + * Compares two floating point values. + * + * @param fOne First value to be compared + * @param fTwo Second value to be compared + * + * @return If arguments are equal, returns 0. + * If the first one is greater, returns 1. + * If the second one is greater, returns -1. + */ +native floatcmp(Float:fOne, Float:fTwo); + +/** + * Returns the square root of a floating point value + * + * @note Same as floatpower(value, 0.5) + * + * @param value Floating point value to get square root from + * + * @return Square root of the input value + */ +native Float:floatsqroot(Float:value); + +/** + * Returns the value raised to the power of the exponent + * + * @param value Floating point value to be raised + * @param exponent The exponent + * + * @return Value raised to the power of the exponent + */ +native Float:floatpower(Float:value, Float:exponent); + +/** + * Returns the logarithm of value + * + * @param value Floating point value to calculate the logarithm for + * @param base The optional logarithmic base to use. + * Defaults to 10, or the natural logarithm + * + * @return Square root of the input value + */ +native Float:floatlog(Float:value, Float:base=10.0); + +/** + * Returns the sine of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the sine from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The sine of a given angle + */ +native Float:floatsin(Float:value, anglemode:mode=radian); + +/** + * Returns the cosine of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the cosine from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The cosine of a given angle + */ +native Float:floatcos(Float:value, anglemode:mode=radian); + +/** + * Returns the tangent of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the tangent from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The tangent of a given angle + */ +native Float:floattan(Float:value, anglemode:mode=radian); + + /** + * Returns the hyperbolic sine of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the hyperbolic sine from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The hyperbolic sine of a given angle + */ +native Float:floatsinh(Float:angle, anglemode:mode=radian); + + /** + * Returns the hyperbolic cosine of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the hyperbolic cosine from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The hyperbolic cosine of a given angle + */ +native Float:floatcosh(Float:angle, anglemode:mode=radian); + + /** + * Returns the hyperbolic tangent of a given angle + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The angle to calculate the hyperbolic tangent from + * @param mode What unit of measurement is the angle specified in + * Defaults to radians + * + * @return The hyperbolic tangent of a given angle + */ +native Float:floattanh(Float:angle, anglemode:mode=radian); + + /** + * Returns the absolute value of a floating point value + * + * @param value The floating point value to get the absolute value from + * + * @return The absolute value + */ +native Float:floatabs(Float:value); + +/* Return the angle of a sine, cosine or tangent. + * The output angle may be in radians, degrees, or grades. */ + + /** + * Returns the angle of the given tangent + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The tangent to calculate the angle from + * @param mode What unit of measurement should the output angle be in + * + * @return The angle of a tangent + */ +native Float:floatatan(Float:angle, {anglemode,_}:radix); + + /** + * Returns the angle of the given cosine + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The cosine to calculate the angle from + * @param mode What unit of measurement should the output angle be in + * + * @return The angle of a cosine + */ +native Float:floatacos(Float:angle, {anglemode,_}:radix); + + /** + * Returns the angle of the given sine + * + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param value The sine to calculate the angle from + * @param mode What unit of measurement should the output angle be in + * + * @return The angle of a sine + */ +native Float:floatasin(Float:angle, {anglemode,_}:radix); + + /** + * Computes the principal value of arctangent of y/x + * + * @note Someone should verify this native, not sure what it actually does. + * @note For available units of measurements(modes) look at the anglemode enum + * + * @param x Value representing the proportion of the x-coordinate. + * @param y Value representing the proportion of the x-coordinate. + * @param mode What unit of measurement should the output angle be in + * + * @return Arctangent of y/x + */ +native Float:floatatan2(Float:x, Float:y, {anglemode,_}:radix); + + + +/* Multiply two floats together */ native Float:floatmul(Float:oper1, Float:oper2); /* Divide the dividend float by the divisor float */ @@ -45,50 +272,6 @@ native Float:floatadd(Float:dividend, Float:divisor); /* Subtract oper2 float from oper1 float */ native Float:floatsub(Float:oper1, Float:oper2); -/* Return the fractional part of a float */ -native Float:floatfract(Float:value); - -/* Round a float into a integer value */ -native floatround(Float:value, floatround_method:method=floatround_round); - -/* Compare two integers. If the two elements are equal, return 0. -* If the first argument is greater than the second argument, return 1, -* If the first argument is less than the second argument, return -1. */ -native floatcmp(Float:fOne, Float:fTwo); - -/* Return the square root of the input value, same as floatpower(value, 0.5) */ -native Float:floatsqroot(Float:value); - -/* Return the value raised to the power of the exponent */ -native Float:floatpower(Float:value, Float:exponent); - -/* Return the logarithm */ -native Float:floatlog(Float:value, Float:base=10.0); - -/* Return the sine, cosine or tangent. - * The input angle may be in radians, degrees or grades. */ -native Float:floatsin(Float:value, anglemode:mode=radian); -native Float:floatcos(Float:value, anglemode:mode=radian); -native Float:floattan(Float:value, anglemode:mode=radian); - -/* Return the hyperbolic sine, cosine or tangent. - * The input angle may be in radians, degrees or grades. */ -native Float:floatsinh(Float:angle, anglemode:mode=radian); -native Float:floatcosh(Float:angle, anglemode:mode=radian); -native Float:floattanh(Float:angle, anglemode:mode=radian); - -/* Return the absolute value */ -native Float:floatabs(Float:value); - -/* Return the angle of a sine, cosine or tangent. - * The output angle may be in radians, degrees, or grades. */ -native Float:floatatan(Float:angle, {anglemode,_}:radix); -native Float:floatacos(Float:angle, {anglemode,_}:radix); -native Float:floatasin(Float:angle, {anglemode,_}:radix); -native Float:floatatan2(Float:x, Float:y, {anglemode,_}:radix); - -#pragma rational Float - /* user defined operators */ native Float:operator*(Float:oper1, Float:oper2) = floatmul; native Float:operator/(Float:oper1, Float:oper2) = floatdiv; @@ -171,14 +354,22 @@ stock bool:operator<=(oper1, Float:oper2) return floatcmp(float(oper1), oper2) <= 0; stock bool:operator!(Float:oper) - return (_:oper & ((-1)/2)) == 0; /* -1 = all bits to 1; /2 = remove most significant bit (sign) - works on both 32bit and 64bit systems; no constant required */ + return (_:oper & ((-1)/2)) == 0; /* -1 = all bits to 1; /2 = remove most significant bit (sign) + works on both 32bit and 64bit systems; no constant required */ /* forbidden operations */ forward operator%(Float:oper1, Float:oper2); forward operator%(Float:oper1, oper2); forward operator%(oper1, Float:oper2); + /** + * Returns whichever value is the smaller one + * + * @param ValueA The first value + * @param ValueB The second value + * + * @return ValueA if it is smaller than ValueB, and vice versa + */ stock Float:floatmin(Float:ValueA, Float:ValueB) { if (ValueA<=ValueB) @@ -189,6 +380,14 @@ stock Float:floatmin(Float:ValueA, Float:ValueB) return ValueB; } + /** + * Returns whichever value is the greater one + * + * @param ValueA The first value + * @param ValueB The second value + * + * @return ValueA if it is greater than ValueB, and vice versa + */ stock Float:floatmax(Float:ValueA, Float:ValueB) { if (ValueA>=ValueB) @@ -198,6 +397,16 @@ stock Float:floatmax(Float:ValueA, Float:ValueB) return ValueB; } + + /** + * Clamps a value between a minimum and a maximum floating point value + * + * @param Value The value to be clamped + * @param MinValue Minimum value + * @param MaxValue Maximum value + * + * @return The Value clamped between MinValue and MaxValue + */ stock Float:floatclamp(Float:Value, Float:MinValue, Float:MaxValue) { if (Value<=MinValue) @@ -210,4 +419,4 @@ stock Float:floatclamp(Float:Value, Float:MinValue, Float:MaxValue) } return Value; -} +} \ No newline at end of file diff --git a/plugins/include/fun.inc b/plugins/include/fun.inc index ffb5242d..b11deffe 100755 --- a/plugins/include/fun.inc +++ b/plugins/include/fun.inc @@ -21,81 +21,284 @@ #pragma loadlib fun #endif -/* Returns 1 if receiver hears sender via voice communication. */ +/** + * Tells whether receiver hears sender via voice communication. + * + * @param receiver Receiver + * @param sender Sender + * + * @return 1 if receiver hears the sender, 0 otherwise. + * @error If receiver or sender are not connected or not + * within the range of 1 to MaxClients. + */ native get_client_listen(receiver, sender); -/* Sets who can listen who. Function returns 0 -* if for some reasons this setting can't be done. */ +/** + * Sets who can listen who. + * + * @param receiver Receiver + * @param sender Sender + * @param listen 1 if receiver should be able to hear sender, 0 if not + * + * @return 0 if the setting can't be done for some reason. + * @error If receiver or sender are not connected or not + * within the range of 1 to MaxClients. + */ native set_client_listen(receiver, sender, listen); -/* Sets player godmode. If you want to disable godmode set only first parameter. */ +/** + * Sets player's godmode + * + * @param index Client index + * @param godmode 1 to enable godmode, 0 to disable + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_godmode(index, godmode = 0); -/* Returns 1 if godmode is set. */ +/** + * Tells whether a player has godmode on + * + * @param index Client index + * + * @return 1 if player has godmode on, 0 if not + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native get_user_godmode(index); -/* Sets player armor. */ +/** + * Sets player's armor amount + * + * @param index Client index + * @param armor The armor amount to set + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_armor(index, armor); -/* Sets player health. */ +/** + * Sets player's health amount + * + * @param index Client index + * @param health The health amount to set + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_health(index, health); -/* Move player to origin. */ +/** + * Moves a player to the given origin + * + * @param index Client index + * @param origin Origin to move a player to + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_origin(index, const origin[3]); -/* Sets player rendering mode. */ +/** + * Sets player's rendering mode + * + * @note A really useful render modes reference: + * https://sites.google.com/site/svenmanor/rendermodes + * + * @param index Client index + * @param fx Rendering effects. One of kRenderFx* constants. + * @param r The amount of red color (0 to 255) + * @param g The amount of green color (0 to 255) + * @param b The amount of blue color (0 to 255) + * @param render Render mode. One of kRender* constants. + * @param amount Render amount (0 to 255) + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_rendering(index, fx = kRenderFxNone, r = 0, g = 0, b = 0, render = kRenderNormal, amount = 0); -/* Gives item to player, name of item can start - * with weapon_, ammo_ and item_. This event - * is announced with proper message to all players. */ + /** + * Gives an item to a player. + * + * @param index Client index + * @param item Classname of the item to give. Should start with either + * "weapon_", "ammo_", "item_" or "tf_weapon_". + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients or item creation fails. + */ native give_item(index, const item[]); -/* Sets hit zones for player. - * Parts of body are as bits: - * 1 - generic - * 2 - head - * 4 - chest - * 8 - stomach - * 16 - left arm - * 32 - right arm - * 64 - left leg - * 128 - right leg */ + /** + * Sets (adds, removes) hit zones for a player. + * + * @note This actually set rules of how any player can hit any other. Example: + * set_user_hitzones(id, target, 2); + * makes @id be able to hit @target only in the head. + * + * @param index Client index + * @param target The target player + * @param body A bitsum of the body parts that can/can't be shot. + * 1 generic + * 2 - head + * 4 - chest + * 8 - stomach + * 16 - left arm + * 32 - right arm + * 64 - left leg + * 128 - right leg + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_hitzones(index = 0, target = 0, body = 255); -/* Get user hitzones. */ +/** + * Gets the set of hit zone "rules" between @index and @target players. + * + * @note For the body part bitsum take a look at the set_user_hitzones() native. + * + * @param index Client index + * @param target The target player + * + * @return The bitsum of @target's body parts @index is able to hit + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native get_user_hitzones(index, target); -/* Sets users max. speed. */ +/** + * Sets player's maximum movement speed + * + * @param index Client index + * @param speed The maximum speed player will be able to run at + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_maxspeed(index, Float:speed = -1.0); -/* Returns users max. speed. */ +/** + * Gets player's maximum movement speed + * + * @param index Client index + * + * @return Player's maximum movement speed + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native Float:get_user_maxspeed(index); -/* Sets users gravity. */ +/** + * Sets player's gravity + * + * @param index Client index + * @param gravity Gravity value to set, 1.0 being normal gravity (800) + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_gravity(index, Float:gravity = 1.0); -/* Returns users gravity. */ +/** + * Gets player's gravity + * + * @param index Client index + * + * @return Player's gravity value, 1.0 being normal gravity (800) + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native Float:get_user_gravity(index); -/* Spawns entity. */ +/** + * Spawns an entity + * + * @param index Entity index + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native spawn(index); -/* Sets player noclip. If you want to disable noclip set only first parameter. */ +/** + * Sets player's noclip + * + * @param index Client index + * @param noclip 1 to enable noclip, 0 to disable + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_noclip(index, noclip = 0); -/* Returns 1 if noclip is set. */ +/** + * Gets player's noclip + * + * @param index Client index + * + * @return 1 if noclip is enabled, 0 if disabled + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native get_user_noclip(index); -/* Returns 1 if player has silent footsteps, 0 if footsteps are set to normal */ +/** + * Tells whether a player has silent footsteps + * + * @param index Client index + * + * @return 1 if silent footsteps are enabled, 0 if not + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native get_user_footsteps(index); -/* Gives player silent footsteps. -* if set = 0 it will return footsteps to normal */ +/** + * Sets player's silent footsteps + * + * @param index Client index + * @param set 1 if player should have silent footsteps, 0 otherwise + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_footsteps(id, set = 1); -/* Strips all weapons from user. */ +/** + * Strips all weapons from a player, including their knife. + * + * @param index Client index + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native strip_user_weapons(index); -/* Sets player frags. */ +/** + * Sets player's frags amount + * + * @param index Client index + * @param frags The amount of frags to set + * + * @noreturn + * @error If player is not connected or not within the range + * of 1 to MaxClients. + */ native set_user_frags(index, frags); diff --git a/plugins/include/nvault.inc b/plugins/include/nvault.inc index af45e9e6..85cadc48 100755 --- a/plugins/include/nvault.inc +++ b/plugins/include/nvault.inc @@ -21,43 +21,131 @@ #pragma loadlib nvault #endif -/* All timestamps are in UNIX epoch form. */ +/** + * @global All timestamps are in UNIX epoch form. + */ -/* Opens a vault by name (such as "myvault") - * Returns a vault id, INVALID_HANDLE otherwise (-1) +/** + * Opens a vault by name. Creates a vault if it doesn't exist yet. + * + * @param name Name of the vault. The vault will be created in + * ${amxx_datadir}/vault directory. + * + * @return The vault handle to be used in other natives. + * INVALID_HANDLE (-1) if not successfully opened. */ native nvault_open(const name[]); -/* Gets a vault value by returning an int - * setting a byref float or setting a string + maxlength +/** + * Retrieves a value from the given key + * + * @note An example of retrieving a string: + * nvault_get(vaultHandle, "myKey", myString, charsmax(myString)); + * + * @param vault A vault handle returned from nvault_open() + * @param key A key to get the value from + * @param ... If three argument are given, gets a float value and + * puts it in the third argument by reference. + * If four arguments are given, gets a string from the + * vault and copies it to the third argument, up to + * 4th argument characters. + * + * @noreturn + * @error On invalid vault handle. */ native nvault_get(vault, const key[], any:...); -/* Looks up a vault value for full information - * Returns 0 if the entry is not found +/** + * Retrieves full information about a vault entry + * + * @param vault A vault handle returned from nvault_open() + * @param key A key to get information from + * @param value A string where the value should be stored + * @param maxlen Maximum length of the @value string + * @param timestamp The timestamp of the entry + * + * @return 1 if an entry was found, 0 otherwise. + * @error On invalid vault handle. */ native nvault_lookup(vault, const key[], value[], maxlen, ×tamp); -/* Sets a vault value (with current timestamp) */ +/** + * Sets value of a vault entry and updates the timestamp. + * + * @note A new entry is created if one with the given key doesn't exist. + * + * @param vault A vault handle returned from nvault_open() + * @param key A key to set the value for + * @param value A value to set + * + * @noreturn + * @error On invalid vault handle. + */ native nvault_set(vault, const key[], const value[]); -/* Sets a permanent vault value (no timestamp) */ +/** + * Sets value of a vault entry and makes it permanent (non-erasable with nvault_prune()). + * + * @note A new entry is created if one with the given key doesn't exist. + * @note Permanent entries have no timestamp. + * + * @param vault A vault handle returned from nvault_open() + * @param key A key to set the permanent value for + * @param value A permanent value to set + * + * @noreturn + * @error On invalid vault handle. + */ native nvault_pset(vault, const key[], const value[]); -/* Prunes the vault for entries that are within the given timestamps. - * This will not erase values set with pset +/** + * Prunes the vault for entries that are within the given timestamps. + * + * @note This will not erase values set with nvault_pset(). + * @note An example of pruning all entries that are older than 24 hours: + * nvault_prune(vaultHandle, 0, get_systime() - (60 * 60 * 24)); + * + * @param vault A vault handle returned from nvault_open() + * @param start The timestamp to start erasing from + * @param end The timestamp to erase to + * + * @noreturn + * @error On invalid vault handle. */ native nvault_prune(vault, start, end); -/* Closes a vault */ +/** + * Closes a vault. + * + * @param vault A vault handle returned from nvault_open() + * + * @noreturn + * @error On invalid vault handle. + */ native nvault_close(vault); -/* Removes a key from the vault */ +/** + * Removes an entry from the vault by its key. + * + * @param vault A vault handle returned from nvault_open() + * @param key The key to remove from the vault + * + * @noreturn + * @error On invalid vault handle. + */ native nvault_remove(vault, const key[]); -/* "Touches" a key to update its timestamp value. - * If stamp is -1 (default), it will use the current time. - * Like the unix command "touch," it will create an empty key - * if the value does not exist. +/** + * "Touches" an entry in the vault, updating its timestamp. + * + * @note If timestamp is equal to -1, it will use the current time. + * @note An empty entry is created if one with the given key doesn't exist. + * + * @param vault A vault handle returned from nvault_open() + * @param key The key to search for + * @param timestamp Update an entry's timestamp to this one. Default is -1. + * + * @noreturn + * @error On invalid vault handle. */ native nvault_touch(vault, const key[], timestamp=-1); diff --git a/plugins/include/sockets.inc b/plugins/include/sockets.inc index 25718cf8..6102a9e3 100755 --- a/plugins/include/sockets.inc +++ b/plugins/include/sockets.inc @@ -96,6 +96,10 @@ native socket_close(_socket); * * @note The amount of bytes than you end up receiving can be less than the one you expected. * + * @note This function will completely block the server until some data arrives + * to the given socket. Use this only if you are sure there is some data + * to be retrieved. You can do that by polling with socket_is_readable(). + * * @param _socket Socket descriptor * @param _data Array to save the data * @param _length Length of the array diff --git a/plugins/include/sqlx.inc b/plugins/include/sqlx.inc index f8bf6619..1c70f04b 100644 --- a/plugins/include/sqlx.inc +++ b/plugins/include/sqlx.inc @@ -30,33 +30,49 @@ enum Handle }; /** - * Creates a connection information tuple. - * This tuple must be passed into connection routines. - * Freeing the tuple is not necessary, but is a good idea if you - * create many of them. You can cache these handles globally. - * !!NOTE!! I have seen most people think that this connects to the DB. - * Nowhere does it say this, and in fact it does not. It only caches - * the connection information, the host/user/pass/etc. - * - * The optional timeout parameter specifies how long connections should wait before - * giving up. If 0, the default (which is undefined) is used. - * + * Creates a connection information tuple. This tuple must be passed + * into connection routines. + * + * @note Freeing the tuple is not necessary, but is a good idea if you create + * many of them. You can cache these handles globally. + * @note This does not connect to the DB; it only caches the connection information. + * + * @param host Database host + * @param user Database user + * @param pass Database password + * @param db Database name to use + * @param timeout Specifies how long connections should wait before giving up. + * If <= 0, the default of 60s is used. + * + * @return A newly created tuple handle to be used in connection routines. */ native Handle:SQL_MakeDbTuple(const host[], const user[], const pass[], const db[], timeout=0); /** * Frees an SQL handle. - * The handle can be to anything (tuple, connection, query, results, etc). - * If you free a database connection, it closes the connection as well. + * + * @note The handle can be to anything (tuple, connection, query, results, etc). + * @note If you free the database connection handle, it closes the connection as well. + * + * @param h Handle to be freed. + * + * @noreturn */ native SQL_FreeHandle(Handle:h); /** * Opens a database connection. - * Returns an SQL handle, which must be freed. - * Returns Empty_Handle on failure. + * + * @param cn_tuple Tuple handle, returned from SQL_MakeDbTuple(). + * @param errcode An error code set by reference. + * @param error String where error string will be stored. + * @param maxlength Maximum length of the error buffer. + * + * @return Returns an SQL connection handle, which must be freed. + * Returns Empty_Handle on failure. + * @error Invalid info tuple handle. */ native Handle:SQL_Connect(Handle:cn_tuple, &errcode, error[], maxlength); @@ -65,38 +81,48 @@ native Handle:SQL_Connect(Handle:cn_tuple, &errcode, error[], maxlength); * Sets the character set of the current connection. * Like SET NAMES .. in mysql, but stays after connection problems. * - * If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery. - * Also note the change will remain until you call this function with another value. - * This native does nothing in SQLite. + * @note If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery. + * @note The change will remain until you call this function with another value. + * @note This native does nothing in SQLite. * * Example: "utf8", "latin1" * - * @param h Database or connection tuple Handle. - * @param charset The character set string to change to. - * @return True, if character set was changed, false otherwise. + * @param h Database or connection tuple Handle. + * @param charset The character set string to change to. + * + * @return True, if character set was changed, false otherwise. */ native bool:SQL_SetCharset(Handle:h, const charset[]); /** * Prepares a query. - * The query must always be freed. - * This does not actually do the query! + * + * @note This does not actually do a query! + * + * @param db Connection handle, returned from SQL_Connect(). + * @param fmt Query string. Can be formated with format specifiers. + * @param ... Additional format specifiers used to format the query. + * + * @return Returns an SQL query handle, which must always be freed. + * Returns Empty_Handle on failure. */ native Handle:SQL_PrepareQuery(Handle:db, const fmt[], any:...); /** * Back-quotes characters in a string for database querying. - * Note: The buffer's maximum size should be 2*strlen(string) to catch - * all scenarios. + * + * @note The buffer's maximum size should be 2*strlen(string) to catch all scenarios. * - * @param db Database handle for localization, or Empty_Handle - * for when a handle is not available. - * @param buffer Buffer to copy to. - * @param buflen Maximum size of the buffer. - * @param string String to backquote (should not overlap buffer). - * @return Length of new string, or -1 on failure. + * @param db Database handle for localization, or Empty_Handle + * for when a handle is not available. + * @param buffer Buffer to copy to. + * @param buflen Maximum size of the buffer. + * @param string String to backquote (should not overlap buffer). + * + * @return Length of new string, or -1 on failure. + * @error Invalid database handle. */ native SQL_QuoteString(Handle:db, buffer[], buflen, const string[]); @@ -105,171 +131,275 @@ native SQL_QuoteString(Handle:db, buffer[], buflen, const string[]); * Note: The buffer's maximum size should be 2*strlen(string) to catch * all scenarios. * - * @param db Database handle for localization, or Empty_Handle - * for when a handle is not available. - * @param buffer Buffer to copy to. - * @param buflen Maximum size of the buffer. - * @param fmt Format of string to backquote (should not overlap buffer). - * @param ... Format arguments. - * @return Length of new string, or -1 on failure. + * @param db Database handle for localization, or Empty_Handle + * for when a handle is not available. + * @param buffer Buffer to copy to. + * @param buflen Maximum size of the buffer. + * @param fmt Format of string to backquote (should not overlap buffer). + * @param ... Format arguments. + * + * @return Length of new string, or -1 on failure. */ native SQL_QuoteStringFmt(Handle:db, buffer[], buflen, const fmt[], any:...); +/** + * Threaded query states. Used to check the state of a complete threaded query. + */ #define TQUERY_CONNECT_FAILED -2 #define TQUERY_QUERY_FAILED -1 #define TQUERY_SUCCESS 0 + /** * Prepares and executes a threaded query. - * This will not interrupt gameplay in the event of a poor/lossed - * connection, however, the interface is more complicated and - * asynchronous. Furthermore, a new connection/disconnection is - * made for each query to simplify driver support. - * The handler should look like: + * @note The handler should look like: + * public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime) + * failstate - One of the three TQUERY_ defines. + * query - Handle to the query, do not free it. + * error - An error message, if any. + * errnum - An error code, if any. + * data - Data array you passed in. + * size - Size of the data array you passed in. + * queuetime - Amount of gametime that passed while the query was resolving. + * @note This will not interrupt gameplay in the event of a poor/lossed + * connection, however, the interface is more complicated and + * asynchronous. Furthermore, a new connection/disconnection is + * made for each query to simplify driver support. + * @note The handle does not need to be freed. * - * @param failstate - One of the three TQUERY_ defines. - * @param query - Handle to the query, do not free it. - * @param error - An error message, if any. - * @param errnum - An error code, if any. - * @param data - Data array you passed in. - * @param size - Size of the data array you passed in. - * @param queuetime - Amount of gametime that passed while the query was resolving. - * - * public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime) + * @param db_tuple Tuple handle, returned from SQL_MakeDbTuple(). + * @param handler A function to be called when the query finishes. It has to be public. + * @param query The query string. + * @param data Additional data array that will be passed to the handler function. + * @param dataSize The size of the additional data array. * - * Note! The handle you pass in is a DB Tuple, NOT an active connection! - * Note! The handle does not need to be freed. - * Also note: This function is not guaranteed to be in another thread - * (in fact - it's not). You're seeing data "after the fact", - * and as such to execute another query you should run - * SQL_ThreadQuery again with new data. + * @noreturn + * @error Thread worker was unable to start. + * Invalid info tuple handle. + * Handler function not found. */ native SQL_ThreadQuery(Handle:db_tuple, const handler[], const query[], const data[]="", dataSize=0); /** - * Executes a query. - * Returns 1 if the query succeeded. - * Returns 0 if the query failed. - * NOTE: You can call this multiple times as long as its parent - * connection is kept open. Each time the result set will be freed - * from the previous call. + * Executes an already prepared query. + * + * @note You can call this multiple times as long as its parent connection is kept open. + * Each time the result set from the previous call will be freed. + * + * @param query Handle of a prepared query to be executed. + * + * @return 1 if the query succeeded, 0 if the query failed. + * @error Invalid query handle. */ native SQL_Execute(Handle:query); + /** * Gets information about a failed query error. - * Returns the errorcode. + * + * @param query Handle of a query to extract the error from. + * @param error Buffer where to store the error string. + * @param maxlength The maximum length of the output buffer. + * + * @return The error code. */ native SQL_QueryError(Handle:query, error[], maxlength); /** - * Returns 1 if there are more results to be read, - * 0 otherwise. + * Checks whether there are more results to be read. + * + * @param query Handle of a query to check. + * + * @return 1 if there are more results, 0 otherwise. + * @error Invalid query handle. */ native SQL_MoreResults(Handle:query); /** - * Tells whether a specific column in the current row - * is NULL or not. + * Tells whether a specific column in the current row is NULL or not. + * + * @param query Handle of a query to check. + * @param column Which column to check for NULL. + * + * @return 1 if the column is NULL, 0 otherwise. + * @error Invalid query handle. + * No result set in this query. + * Invalid column. */ native SQL_IsNull(Handle:query, column); + /** * Retrieves the current result. - * A successful query starts at the first result, - * so you should not call SQL_NextRow() first. - * Passing no extra params - return int - * Passing one extra param - return float in 1st extra arg - * Passing two extra params - return string in 1st arg, max length in 2nd - * Example: - * new num = SQL_ReadResult(query, 0) - * new Float:num2 - * new str[32] - * SQL_ReadResult(query, 1, num2) - * SQL_ReadResult(query, 2, str, 31) + * + * @note A successful query starts at the first result, so you should not call + * SQL_NextRow() first. + * + * @note Example how to get different types of values: + * new num = SQL_ReadResult(query, 0) + * new Float:num2 + * new string[32] + * SQL_ReadResult(query, 1, num2) + * SQL_ReadResult(query, 2, string, charsmax(string)) + * + * @param query Handle of a query to read results from. + * @param column Which column to get the value from. + * @param ... Passing no extra arguments - returns an integer. + * Passing one extra argument - returns a float in the first extra argument + * Passing two extra params - returns a string in the first argument + * with a maximum string length in the second argument. + * + * @return If no extra arguments are passed, returns an integer value. + * @error Invalid query handle. */ native SQL_ReadResult(Handle:query, column, any:...); /** - * Advances to the next result (return value should be ignored). + * Advances to the next result (row). + * + * @param query Handle of a query. + * + * @noreturn + * @error Invalid query handle. + * No result set in this query. */ native SQL_NextRow(Handle:query); -/** - * Returns the number of affected rows. +/** + * Returns the number of affected rows by a query. + * + * @param query Handle of a query to check. + * + * @return The number of affected rows. + * @error Invalid query handle. */ native SQL_AffectedRows(Handle:query); /** - * Returns the number of rows total. + * The number of retrieved rows (results) after a query. + * + * @param query Handle of a query to check. + * + * @return The number of retrieved rows by the query. + * @error Invalid query handle. */ native SQL_NumResults(Handle:query); /** - * Returns the number of columns total. + * Returns the total number of columns. + * + * @param query Handle of a query to check. + * + * @return The number of retrieved columns by the query. + * @error Invalid query handle. + * No result set in this query. */ native SQL_NumColumns(Handle:query); -/** - * Returns the name of a column. - * Errors on a bad field number. +/** + * Retrieves the name of a column by its index. + * + * @param query Handle of a query. + * @param num The number (index) of a column to retrieve the name from. + * @param name Buffer where to store the column's name. + * @param maxlength Maximum length of the output buffer. + * + * @noreturn + * @error Invalid query handle. + * No result set in this query. + * Invalid column index. */ native SQL_FieldNumToName(Handle:query, num, name[], maxlength); /** - * Returns the number of a named column, or -1 if not found. + * Retrieves the number of a named column. + * + * @param query Handle of a query. + * @param name Name to search for. + * + * @return Column index if found (>= 0); -1 otherwise. + * @error Invalid query handle. + * No result set in this query. */ native SQL_FieldNameToNum(Handle:query, const name[]); /** * Rewinds a result set to the first row. + * + * @param query Handle of a query to rewind the result set of. + * + * @noreturn + * @error Invalid query handle. + * No result set in this query. */ native SQL_Rewind(Handle:query); /** - * Returns the insert id of the last INSERT query. - * Returns 0 otherwise. + * Retrieves the instert ID of the latest INSERT query. + * + * @param query Handle of a query. + * + * @return The insert ID of the latest INSERT query. + * @error Invalid query handle. */ native SQL_GetInsertId(Handle:query); /** - * Returns which driver this plugin is currently bound to. + * Retrieves which driver is this plugin currently bound to. + * + * @param driver Buffer to store the driver name in. + * @param maxlen Maximum length of the output buffer. + * + * @noreturn */ native SQL_GetAffinity(driver[], maxlen); + /** - * Sets driver affinity. You can use this to force a particular - * driver implementation. This will automatically change all SQL - * natives in your plugin to be "bound" to the module in question. - * If no such module is found, it will return 0. This isn't necessarily bad - - * the user might have typed the wrong driver. Unless your plugin is built - * to handle different driver types at once, you should let this error pass. - * Note, that using this while you have open handles to another database - * type will cause problems. I.e., you cannot open a handle, switch - * affinity, then close the handle with a different driver. - * Switching affinity is an O(n*m) operation, where n is the number of - * SQL natives and m is the number of used natives in total. - * Intuitive programmers will note that this causes problems for threaded queries. - * You will have to either force your script to work under one affinity, or to - * pack the affinity type into the query data, check it against the current, then - * set the new affinity if necessary. Then, restore the old for safety. + * Sets driver affinity. You can use this to force a particular driver implementation. + * This will automatically change all SQL natives in your plugin to be "bound" to + * the module in question. + * + * @note Using this while you have open handles to another database type will + * cause problems. I.e., you cannot open a handle, switch affinity, + * then close the handle with a different driver. + * @note Switching affinity is an O(n * m) operation, where n is the number of + * SQL natives and m is the number of used natives in total. + * @note Intuitive programmers will note that this causes problems for + * threaded queries. You will have to either force your script to work + * under one affinity, or to pack the affinity type into the query data, + * check it against the current, then set the new affinity if necessary. + * Then, restore the old one for safety. + * + * @param driver The name of a driver to use. + * + * @return If no module with the given name is found, returns 0. + * Unless your plugin is bult to handle different driver + * types at once, you should let this error pass. */ native SQL_SetAffinity(const driver[]); /** * Returns the original query string that a query handle used. + * + * @param query Handle of a query. + * @param buffer Buffer where to put the query string in. + * @param maxlength The maximum length of the output buffer. + * + * @noreturn + * @error Invalid query handle. */ native SQL_GetQueryString(Handle:query, buffer[], maxlength); @@ -278,18 +408,26 @@ native SQL_GetQueryString(Handle:query, buffer[], maxlength); * result set if one is available. Otherwise, the current result set is * destroyed and will no longer be accessible. * - * This function will always return false on SQLite, and when using threaded - * queries in MySQL. Nonetheless, it has the same effect of removing the last - * result set. + * @note This function will always return false on SQLite, and when using threaded + * queries in MySQL. Nonetheless, it has the same effect of removing the last + * result set. * - * @param query Query Handle. - * @return True on success, false on failure. + * @param query Query Handle. + * + * @return True on success, false on failure. + * @error Invalid query handle. + * No result set in this query. */ native bool:SQL_NextResultSet(Handle:query); + /** - * This function can be used to find out if a table in a Sqlite database exists. - * (updated for newer API) + * This function can be used to find out if a table in a SQLite database exists. + * + * @param db Connection handle returned from SQL_Connect(). + * @param table The table name to check for. + * + * @return True if it exists, false otherwise. */ stock bool:sqlite_TableExists(Handle:db, const table[]) { @@ -311,7 +449,14 @@ stock bool:sqlite_TableExists(Handle:db, const table[]) /** * Use this for executing a query where you don't care about the result. - * Returns 0 on failure, 1 on success + * + * @param db Connection handle returned from SQL_Connect(). + * @param query The query string. + * @param error If an error occurs, it will be placed into this buffer. + * @param maxlength Maximum length of the error buffer. + * @param rows Optional. If put, retrieves the number of rows the query returned. + * + * @return 1 on success, 0 on failure. */ stock SQL_SimpleQuery(Handle:db, const query[], error[]="", maxlength=0, &rows=0) { @@ -331,9 +476,20 @@ stock SQL_SimpleQuery(Handle:db, const query[], error[]="", maxlength=0, &rows=0 return 1; } + /** * Use this for executing a query where you don't care about the result. - * Returns 0 on failure, 1 on success + * + * @note Differs from SQL_SimpleQuery() because the query can be formated. + * + * @param db Connection handle returned from SQL_Connect(). + * @param error If an error occurs, it will be placed into this buffer. + * @param maxlength The maximum length of the error buffer. + * @param rows Optional. If put, retrieves the number of rows the query returned. + * @param fmt The query string that can be formated with format specifiers. + * @param ... Additional arguments for formating the query. + * + * @return 1 on success, 0 on failure. */ stock SQL_SimpleQueryFmt(Handle:db, error[]="", maxlength=0, &rows=0, const fmt[], any:...) { @@ -358,7 +514,13 @@ stock SQL_SimpleQueryFmt(Handle:db, error[]="", maxlength=0, &rows=0, const fmt[ /** * Use this for executing a query and not caring about the error. - * Returns -1 on error, >=0 on success (with number of affected rows) + * + * @param db A connection handle returned from SQL_Connect(). + * @param queryfmt The query string that can be formated with format specifiers. + * @pram ... Additional arguments for formating the query. + * + * @return 1 on error. + * >= 0 on success (with the number of affected rows). */ stock SQL_QueryAndIgnore(Handle:db, const queryfmt[], any:...) { @@ -382,6 +544,14 @@ stock SQL_QueryAndIgnore(Handle:db, const queryfmt[], any:...) return ret; } +/** + * Use this for making a standard DB Tuple, using AMXX's database info cvars. + * + * @param timeout Specifies how long connections should wait before giving up. + * If 0, the value is read from "amx_sql_timeout" cvar. + * + * @return A newly created tuple handle to be used in connection routines. + */ stock Handle:SQL_MakeStdTuple(timeout = 0) { static host[64], user[32], pass[32], db[128]; diff --git a/plugins/include/vector.inc b/plugins/include/vector.inc index e30b52dd..ee764294 100644 --- a/plugins/include/vector.inc +++ b/plugins/include/vector.inc @@ -16,34 +16,93 @@ #endif #define _corevector_included -/* Used for angle_vector() */ +/** + * Used for angle_vector() + */ #define ANGLEVECTOR_FORWARD 1 #define ANGLEVECTOR_RIGHT 2 #define ANGLEVECTOR_UP 3 -/* Returns distance between two vectors. */ +/** + * Calculates the distance between two input vectors. + * + * @param origin1 The first vector + * @param origin2 The second vector + * + * @return The distance between two input vectors + */ native get_distance(const origin1[3], const origin2[3]); -/* Gets distance between two origins (float). */ +/** + * Calculates the distance between two input float vectors. + * + * @param origin1 The first vector + * @param origin2 The second vector + * + * @return The distance between two input vectors + */ native Float:get_distance_f(const Float:Origin1[3], const Float:Origin2[3]); -/* Gives you a velocity in the direction a player is looking, iVelocity is the multiplier. */ +/** + * Calculates velocity in the direction player is looking. + * + * @param iIndex Client index + * @param iVelocity Multiply vRetValue length by this much + * @param vRetValue Store the calculated velocity in this vector. + * + * @noreturn + * @error If client is not connected or client index is not + * within the range of 1 to MaxClients. + */ native velocity_by_aim(iIndex, iVelocity, Float:vRetValue[3]); -/* Changes a vector into an angle vector. */ +/** + * Changes a vector into an angle vector. + * + * @param fVector Input vector + * @param vReturn Output angle vector + * + * @noreturn + */ native vector_to_angle(const Float:fVector[3], Float:vReturn[3]); -/* Changes an angle vector into a vector. */ +/** + * Changes an angle vector into a vector. + * + * @param vector Input angle vector + * @param FRU One of the ANGLEVECTOR_* constants + * @param ret Output vector + * + * @noreturn + */ native angle_vector(const Float:vector[3], FRU, Float:ret[3]); -/* Gets the length of a vector (float[3]). */ +/** + * Calculates the length of a vector. + * + * @param vVector Input vector + * + * @return Length of the input vector + */ native Float:vector_length(const Float:vVector[3]); -/* Gets the distance between 2 vectors (float[3]). */ +/** + * Calculates the distance between two vectors. + * + * @param vVector The first vector + * @param vVector2 The second vector + * + * @return Distance between two input vectors + */ native Float:vector_distance(const Float:vVector[3], const Float:vVector2[3]); -/* Changes an integer vec to a floating vec - * This is not a for loop because that's slower +/** + * Converts an integer vector to a floating point vector. + * + * @param IVec Input integer vector + * @param FVec Output float vector + * + * @noreturn */ stock IVecFVec(const IVec[3], Float:FVec[3]) { @@ -54,7 +113,14 @@ stock IVecFVec(const IVec[3], Float:FVec[3]) return 1; } -/* Changes a float vec to an integer vec */ +/** + * Converts a floating point vector into an integer vector. + * + * @param FVec Input float vector + * @param IVec Output integer vector + * + * @noreturn + */ stock FVecIVec(const Float:FVec[3], IVec[3]) { IVec[0] = floatround(FVec[0]); diff --git a/plugins/include/xs.inc b/plugins/include/xs.inc index a7ca0550..9a297577 100755 --- a/plugins/include/xs.inc +++ b/plugins/include/xs.inc @@ -8,45 +8,41 @@ // Additional exceptions apply. For full license details, see LICENSE.txt or visit: // https://alliedmods.net/amxmodx-license -// -// XS Library -// Version 0.1 -// -// MACROS THAT YOU CAN DEFINE BEFORE INCLUDING XS.INC: -// XS_FLEQ_TOLERANCE: -// Tolerance that is used for XS_FLEQ float nearly-equal comparisions -// DEFAULT: 0.000005 -// XS_DEBUG -// Turn debug logging on -// DEFAULT: 0 -// XS_LOGBUFFER_SIZE -// Buffer size for logging -// DEFAULT: 512 -// XS_TASK_MAXPARAMS -// Maximal parameter count for managed tasks -// DEFAULT: 8 -// XS_TASK_MAXPARAMSIZE -// Maximal size of string parameter for tasks -// Has to be power of 2 and has to be >= 8 -// DEFAULT: 512 -// XS_TASK_MANAGEDIDS -// Number of managed IDs for tasks. -// DEFAULT: 2048 -// XS_REPLACEBUF_SIZE -// DEFAULT: 3072 -// -// -// NOTES: -// On AMX, VexdUM is required for some math functions -// -// xs__ / XS__ (2 underscores) stuff is meant to be intern -// -// untested: never tested -// half-tested: succesfully used in other applications; not extensively tested in xs though -// tested: fully tested -// -// If you have any useful functions / ideas for functions, please tell me. -// +/** + * XS Library + * Version 0.1 + * + * MACROS THAT YOU CAN DEFINE BEFORE INCLUDING XS.INC: + * XS_FLEQ_TOLERANCE: + * Tolerance that is used for XS_FLEQ float nearly-equal comparisions + * DEFAULT: 0.000005 + * XS_DEBUG + * Turn debug logging on + * DEFAULT: 0 + * XS_LOGBUFFER_SIZE + * Buffer size for logging + * DEFAULT: 512 + * XS_TASK_MAXPARAMS + * Maximal parameter count for managed tasks + * DEFAULT: 8 + * XS_TASK_MAXPARAMSIZE + * Maximal size of string parameter for tasks + * Has to be power of 2 and has to be >= 8 + * DEFAULT: 512 + * XS_TASK_MANAGEDIDS + * Number of managed IDs for tasks. + * DEFAULT: 2048 + * XS_REPLACEBUF_SIZE + * DEFAULT: 3072 + * + * NOTES: + * On AMX, VexdUM is required for some math functions + * xs__ / XS__ (2 underscores) stuff is meant to be intern + * untested: never tested + * half-tested: succesfully used in other applications; not extensively tested in xs though + * tested: fully tested + * If you have any useful functions / ideas for functions, please tell me. +*/ #if defined _xs_included #endinput @@ -153,72 +149,137 @@ new xs__global_null = 0; /****** BASIC STUFF ******/ -// Returns -1 if num is negative, 0 if num is 0, 1 if num is positive -// tested +/** + * Gets the sign of a value. + * + * @param num Number to get the sign from. + * + * @return -1 if the number is negative, + * 0 if the number is equal to 0, + * 1 if the number is positive. + */ stock xs_sign(num) { return (num < 0) ? -1 : ((num == 0) ? 0 : 1); } -// Returns -1 if num is negative, 0 if num is 0, 1 if num is positive -// tested +/** + * Gets the sign of a float value. + * + * @param num Number to get the sign from. + * + * @return -1 if the number is negative, + * 0 if the number is equal to 0, + * 1 if the number is positive. + */ stock xs_fsign(Float:num) { return (num < 0.0) ? -1 : ((num == 0.0) ? 0 : 1); } -// Returns absolute value -// tested +/** + * Gets the absolute value of a number. + * + * @param num Number to get the absolute value from. + * + * @return Absolute value of the input number. + */ stock xs_abs(num) { return (num < 0) ? -num : num; } -// is power of 2? (== can be expressed as 1<= ((%2) - XS_FLEQ_TOLERANCE))) -// 1/sqrt -// tested +/** + * Calculates the reciprocal of the square root of the input value. + * + * @param x The input value. + * + * @return The reciprocal of the square root of the input value. + */ stock Float:xs_rsqrt(Float:x) { return 1.0 / floatsqroot(x); } -// sqrt -// tested +/** + * Calculates the square root of the input value. + * + * @note This is an alias for floatsqroot(). + * + * @param x The input value. + * + * @return The square root of the input value. + */ stock Float:xs_sqrt(Float:x) { return floatsqroot(x); @@ -299,13 +360,23 @@ stock xs__internalseed=0x546875; #define XS__IL_RMULT 1103515245 -// tested +/** + * Sets the seed for the random number generation. + * + * @param x The seed to set. + * + * @noreturn + */ stock xs_seed(seed) { xs__internalseed = seed; } -// tested +/** + * Retrieves a random integer. + * + * @return A random integer. + */ stock xs_irand() { new lo, hi, ll, lh, hh, hl; @@ -322,13 +393,26 @@ stock xs_irand() return result; } -// tested +/** + * Retrieves a random float. + * + * @return A random float. + */ stock Float:xs_frand() { return float(xs_irand()) / float(xs_get_maxnum()); // -1/2 should be the biggest possible positive number } -// tested +/** + * Retrieves a random integer between the specified values. + * + * @note @pmax has to be greater than @pmin! + * + * @param pmin The minimum value. + * @param pmax The maximum value. + * + * @return A random integer. + */ stock xs_irand_range(pmin, pmax) { xs_assert_dbg(pmax - pmin >= 0, "xs_irand_range: pmin > pmax"); @@ -342,8 +426,16 @@ stock xs_irand_range(pmin, pmax) // *** vectors -// Set vec components to values -// tested +/** + * Sets vector's components to specified values. + * + * @param vec The vector to set values to. + * @param x The X component to be set. + * @param y The Y component to be set. + * @param z The Z component to be set. + * + * @noreturn + */ stock xs_vec_set(Float:vec[], Float:x, Float:y, Float:z) { vec[0] = x; @@ -351,8 +443,15 @@ stock xs_vec_set(Float:vec[], Float:x, Float:y, Float:z) vec[2] = z; } -// Add vec -// tested +/** + * Adds two vectors. + * + * @param in1 The first vector to add. + * @param in2 The second vector to add. + * @param out The output vector. Can be one of the input vectors. + * + * @noreturn + */ stock xs_vec_add(const Float:in1[], const Float:in2[], Float:out[]) { out[0] = in1[0] + in2[0]; @@ -360,8 +459,15 @@ stock xs_vec_add(const Float:in1[], const Float:in2[], Float:out[]) out[2] = in1[2] + in2[2]; } -// Subtract vec -// untested, but should work +/** + * Subtracts one vector from another one. + * + * @param in1 Vector to subtract from. + * @param in2 Vector to subtract from the first one. + * @param out The output vector. Can be one of the input vectors. + * + * @noreturn + */ stock xs_vec_sub(const Float:in1[], const Float:in2[], Float:out[]) { out[0] = in1[0] - in2[0]; @@ -369,8 +475,16 @@ stock xs_vec_sub(const Float:in1[], const Float:in2[], Float:out[]) out[2] = in1[2] - in2[2]; } -// Adds the second vector scaled by a scalar to the first -// tested +/** + * Adds the second vector scaled by a scalar to the first. + * + * @param in1 Vector to add to. + * @param in2 Vector to scale and add. + * @param scalar Scalar to scale the second vector with. + * @param out The output vector. Can be one of the input vectors. + * + * @noreturn + */ stock xs_vec_add_scaled(const Float:in1[], const Float:in2[], Float:scalar, Float:out[]) { out[0] = in1[0] + in2[0] * scalar; @@ -378,8 +492,16 @@ stock xs_vec_add_scaled(const Float:in1[], const Float:in2[], Float:scalar, Floa out[2] = in1[2] + in2[2] * scalar; } -// Subtracts the second vector scaled by a scalar to the first -// tested +/** + * Subtracts the second vector scaled by a scalar from the first one. + * + * @param in1 Vector to subtract from. + * @param in2 Vector to scale and subtract. + * @param scalar Scalar to scale the second vector with. + * @param out The output vector. Can be one of the input vectors. + * + * @noreturn + */ stock xs_vec_sub_scaled(const Float:in1[], const Float:in2[], Float:scalar, Float:out[]) { out[0] = in1[0] - in2[0] * scalar; @@ -387,22 +509,47 @@ stock xs_vec_sub_scaled(const Float:in1[], const Float:in2[], Float:scalar, Floa out[2] = in1[2] - in2[2] * scalar; } -// Are vectors equal? -// untested, but should work +/** + * Checks if two vectors are equal. + * + * @note If you need to check if two vectors are nearly equal, + * take a look at xs_vec_nearlyequal(). + * + * @param vec1 The first input vector to check. + * @param vec2 The second input vector to check. + * + * @return 1 if vectors are equal, 0 otherwise. + */ stock bool:xs_vec_equal(const Float:vec1[], const Float:vec2[]) { return (vec1[0] == vec2[0]) && (vec1[1] == vec2[1]) && (vec1[2] == vec2[2]); } -// Are vectors nearly equal? -// tested +/** + * Checks if two vectors are nearly equal. + * + * @note If you need to check if two vectors are exactly equal, + * take a look at xs_vec_equal(). + * + * @param vec1 The first input vector to check. + * @param vec2 The second input vector to check. + * + * @return 1 if vectors are equal, 0 otherwise. + */ stock bool:xs_vec_nearlyequal(const Float:vec1[], const Float:vec2[]) { return XS_FLEQ(vec1[0], vec2[0]) && XS_FLEQ(vec1[1], vec2[1]) && XS_FLEQ(vec1[2], vec2[2]); } -// multiply vector by scalar -// tested +/** + * Multiply a vector by a scalar value. + * + * @param vec The vector to be multiplied. + * @param scalar The scalar value to multiply the vector with. + * @param out The output vector. Can be the same as the input vector. + * + * @noreturn + */ stock xs_vec_mul_scalar(const Float:vec[], Float:scalar, Float:out[]) { out[0] = vec[0] * scalar; @@ -410,8 +557,15 @@ stock xs_vec_mul_scalar(const Float:vec[], Float:scalar, Float:out[]) out[2] = vec[2] * scalar; } -// divide vector by scalar -// untested, but should work +/** + * Divide a vector by a scalar value. + * + * @param vec The vector to be divided. + * @param scalar The scalar value to divide the vector with. + * @param out The output vector. Can be the same as the input vector. + * + * @noreturn + */ stock xs_vec_div_scalar(const Float:vec[], Float:scalar, Float:out[]) { new Float:__tmp = 1.0 / scalar; @@ -420,22 +574,38 @@ stock xs_vec_div_scalar(const Float:vec[], Float:scalar, Float:out[]) out[2] = vec[2] * __tmp; } -// Compute vector length -// tested +/** + * Computes the length of a vector. + * + * @param vec The vector to compute the length of. + * + * @return The length of the input vector. + */ stock Float:xs_vec_len(const Float:vec[]) { return xs_sqrt(vec[0]*vec[0] + vec[1]*vec[1] + vec[2]*vec[2]); } -// Compute 2D vector length -// tested +/** + * Computes the length of a 2D vector. + * + * @param vec The vector to compute the length of. + * + * @return The length of the input vector. + */ stock Float:xs_vec_len_2d(const Float:vec[]) { return xs_sqrt(vec[0]*vec[0] + vec[1]*vec[1]); } -// Compute distance between two vectors -// tested +/** + * Computes the distance between two vectors (points). + * + * @param vec1 First vector. + * @param vec2 Second vector. + * + * @return The distance between two vectors. + */ stock Float:xs_vec_distance(const Float:vec1[], const Float:vec2[]) { return xs_sqrt((vec1[0]-vec2[0]) * (vec1[0]-vec2[0]) + @@ -443,16 +613,29 @@ stock Float:xs_vec_distance(const Float:vec1[], const Float:vec2[]) (vec1[2]-vec2[2]) * (vec1[2]-vec2[2])); } -// Compute distance between two 2D vectors -// tested +/** + * Computes the distance between two 2D vectors (points). + * + * @param vec1 First vector. + * @param vec2 Second vector. + * + * @return The distance between two vectors. + */ stock Float:xs_vec_distance_2d(const Float:vec1[], const Float:vec2[]) { return xs_sqrt((vec1[0]-vec2[0]) * (vec1[0]-vec2[0]) + (vec1[1]-vec2[1]) * (vec1[1]-vec2[1])); } -// Normalize vec -// tested +/** + * Normalizes a vector. Normalized vector is a vector with the length of 1 unit, + * but with the same direction as the original vector. + * + * @param vec The vector to be normalized. + * @param out The output vector. Can be the same as the input vector. + * + * @noreturn + */ stock xs_vec_normalize(const Float:vec[], Float:out[]) { new Float:invlen = xs_rsqrt(vec[0]*vec[0] + vec[1]*vec[1] + vec[2]*vec[2]); @@ -461,8 +644,15 @@ stock xs_vec_normalize(const Float:vec[], Float:out[]) out[2] = vec[2] * invlen; } -// Store the cross product of vec1 and vec2 in out -// tested +/** + * Computes the cross product of two vectors. + * + * @param vec1 The first vector operand of the cross operation. + * @param vec2 The second vector operand of the cross operation. + * @param out The output vector. *Can't* be one of the input vectors. + * + * @noreturn + */ stock xs_vec_cross(const Float:vec1[], const Float:vec2[], Float:out[]) { out[0] = vec1[1]*vec2[2] - vec1[2]*vec2[1]; @@ -470,15 +660,27 @@ stock xs_vec_cross(const Float:vec1[], const Float:vec2[], Float:out[]) out[2] = vec1[0]*vec2[1] - vec1[1]*vec2[0]; } -// Compute vec1 dot vec2 -// tested +/** + * Computes the dot product of two vectors. + * + * @param vec1 The first vector operand of the dot operation. + * @param vec2 The second vector operand of the dot operation. + * + * @return The dot product of two input vectors. + */ stock Float:xs_vec_dot(const Float:vec1[], const Float:vec2[]) { return vec1[0]*vec2[0] + vec1[1]*vec2[1] + vec1[2]*vec2[2]; } -// Negate vec into out -// untested, but should work +/** + * Negates a vector. + * + * @param vec The vector to negate. + * @param out The output vector. Can be the same as the input vector. + * + * @noreturn + */ stock xs_vec_neg(const Float:vec[], Float:out[]) { out[0] = -vec[0]; @@ -486,8 +688,14 @@ stock xs_vec_neg(const Float:vec[], Float:out[]) out[2] = -vec[2]; } -// Copy vec -// untested, but should work +/** + * Copies a vector into another one. + * + * @param vecIn The vector to copy. + * @param vecOut The output vector where to copy the input vector. + * + * @noreturn + */ stock xs_vec_copy(const Float:vecIn[], Float:vecOut[]) { vecOut[0] = vecIn[0]; @@ -495,15 +703,28 @@ stock xs_vec_copy(const Float:vecIn[], Float:vecOut[]) vecOut[2] = vecIn[2]; } -// Compute angle between vec1 and vec2 -// tested +/** + * Computes the angle between two vectors. + * + * @param vec1 The first vector. + * @param vec2 The second vector. + * + * @return The angle between two input vectors in degrees. + */ stock Float:xs_vec_angle(const Float:vec1[], const Float:vec2[]) { return xs_rad2deg(xs_acos(xs_vec_dot(vec1, vec2), radian)); } -// Reflect vec about normal -// untested +/** + * Reflects a vector about a normal. + * + * @param vec The vector to be reflected. + * @param normal The normal vector about which to reflect. + * @param out The output reflected vector. + * + * @noreturn + */ stock xs_vec_reflect(const Float:vec[], const Float:normal[], Float:out[]) { // normalize(vec) - (normal * 2.0 * (tmp . normal)) * length(vec) @@ -524,7 +745,16 @@ stock xs_vec_reflect(const Float:vec[], const Float:normal[], Float:out[]) xs_vec_sub(tmp1, tmp2, out); } -// Turn a 3D vector into a 2D vector +/** + * Turns a 3D vector into a 2D vector. + * + * @note This function just ignores the Z (3rd) component of a 3D vector. + * + * @param vec A 3D vector to turn into a 2D vector. + * @param out The output 2D vector. + * + * @noreturn + */ stock xs_vec_make2d(const Float:vec[3], Float:out[2]) { out[0] = vec[0]; @@ -541,8 +771,17 @@ stock xs_vec_make2d(const Float:vec[3], Float:out[2]) #define XS_PLANE_D 3 -// Set a plane to specific values -// tested +/** + * Sets a plane to the specified values. + * + * @param plane The plane to set the values to. It's a 4D vector. + * @param a The first component of a plane to be set. + * @param b The second component of a plane to be set. + * @param c The third component of a plane to be set. + * @param d The fouth component of a plane to be set. + * + * @noreturn + */ stock xs_plane_set(Float:plane[], Float:a, Float:b, Float:c, Float:d) { plane[XS_PLANE_A] = a; @@ -551,8 +790,16 @@ stock xs_plane_set(Float:plane[], Float:a, Float:b, Float:c, Float:d) plane[XS_PLANE_D] = d; } -// Construct a plane out of 3 points -// tested +/** + * Constructs a plane out of 4 points in space. + * + * @param plane The output plane to store the newly created plane. + * @param p1 The first point of a plane. + * @param p2 The second point of a plane. + * @param p3 The third point of a plane. + * + * @noreturn + */ stock xs_plane_3p(Float:plane[], const Float:p1[], const Float:p2[], const Float:p3[]) { new Float:normalA[3], Float:normalB[3]; @@ -580,7 +827,17 @@ stock xs_plane_3p(Float:plane[], const Float:p1[], const Float:p2[], const Float } -// untested, but should work +/** + * Checks if two planes are equal. + * + * @note If you have to check if two planes are just nearly equal, + * take a look at xs_plane_nearlyequal(). + * + * @param plane1 The first plane to check. + * @param plane2 The second plane to check. + * + * @return 1 if planes are equal, 0 otherwise. + */ stock bool:xs_plane_equal(const Float:plane1[], const Float:plane2[]) { if ( (plane1[0] == plane2[0]) && @@ -591,7 +848,17 @@ stock bool:xs_plane_equal(const Float:plane1[], const Float:plane2[]) return false; } -// untested, but should work +/** + * Checks if two planes are nearly equal. + * + * @note If you have to check if two planes are exactly equal, + * take a look at xs_plane_equal(). + * + * @param plane1 The first plane to check. + * @param plane2 The second plane to check. + * + * @return 1 if planes are nearly equal, 0 otherwise. + */ stock bool:xs_plane_nearlyequal(const Float:plane1[], const Float:plane2[]) { if ( XS_FLEQ(plane1[0], plane2[0]) && @@ -602,18 +869,32 @@ stock bool:xs_plane_nearlyequal(const Float:plane1[], const Float:plane2[]) return false; } -// Compute distance between plane and point -// tested +/** + * Computes the distance between a plane and a point. + * + * @param plane The plane to check the distance from. + * @param point The point to check the distance to. + * + * @return The distance between the input plane and point. + */ stock Float:xs_plane_dst2point(const Float:plane[], const Float:point[]) { // return normal dot point + D return xs_vec_dot(plane, point) + plane[XS_PLANE_D]; } -// Checks whether plane intersects with the ray starting and rayStart and going to rayDir direction. -// If yes, returns true and sets out to the intersection point -// Otherwise, returns false -// tested +/** + * Checks whether a plane intersects with the ray starting at @rayStart and + * going to @rayDir direction. + * If it does intersect, outputs the intersection point in @out. + * + * @param plane The plane to check intersection with. + * @param rayStart The starting point of the ray. + * @param rayDir Direction in which the ray is going. + * @param out The vector to copy the intersection point to, if it exists. + * + * @return true if they intersect, false otherwise. + */ stock bool:xs_plane_rayintersect(const Float:plane[], const Float:rayStart[], const Float:rayDir[], Float:out[]) { new Float:a = xs_vec_dot(plane, rayDir); @@ -640,15 +921,28 @@ stock bool:xs_plane_rayintersect(const Float:plane[], const Float:rayStart[], co return true; } -// Is point on plane? -// tested +/** + * Checks if a point is on a specified plane. + * + * @param plane The plane to check. + * @param point The point to check. + * + * @return true if the point is on the plane, false otherwise. + */ stock bool:xs_point_onplane(const Float:plane[], const Float:point[]) { return XS_FLEQ(xs_plane_dst2point(plane, point), 0.0); } -// Project point on plane -// tested +/** + * Projects a point on the plane. Stores the projected point in @out. + * + * @param plane The plane to project the point onto. + * @param point The point to project onto the plane. + * @param out The vector to copy the projected point into. + * + * @noreturn + */ stock xs_projpoint_onplane(const Float:plane[], const Float:point[], Float:out[]) { new Float:__tmp[3]; @@ -658,8 +952,14 @@ stock xs_projpoint_onplane(const Float:plane[], const Float:point[], Float:out[] xs_vec_sub(point, __tmp, out); } -// Copy plane -// untested, but should work +/** + * Copies a plane. + * + * @param planeIn The plane to copy. + * @param planeOut The plane to store the copy into. + * + * @noreturn + */ stock xs_plane_copy(const Float:planeIn[], Float:planeOut[]) { planeOut[0] = planeIn[0]; @@ -669,14 +969,22 @@ stock xs_plane_copy(const Float:planeIn[], Float:planeOut[]) } /****** HL ENGINE SPECIFIC STUFF ******/ -// Compute forward, right and up vector from angles -// half-tested // angle indexes #define XS_PITCH 0 // up / down #define XS_YAW 1 // left / right #define XS_ROLL 2 // fall over +/** + * Computes forward, right and up vectors from given angles. + * + * @param angles Angles to compute vectors from. + * @param fwd The vector to store the forward vector into. + * @param right The vector to store the right vector into. + * @param up The vector to store the up vector into. + * + * @noreturn + */ stock xs_anglevectors(const Float:angles[3], Float:fwd[3], Float:right[3], Float:up[3]) { // sin (s) and cos (c) for yaw (y), pitch (p) and roll (r) @@ -703,7 +1011,14 @@ stock xs_anglevectors(const Float:angles[3], Float:fwd[3], Float:right[3], Float } /****** STRING FUNCS *******/ -// tested +/** + * Finds a character in a string and returns its position in the string. + * + * @param str The string to search in. + * @param chr The character to search for in the string. + * + * @return The character position if found, -1 otherwise. + */ stock xs_strchr(const str[], chr) { for (new i = 0; str[i] != 0; ++i) @@ -714,11 +1029,17 @@ stock xs_strchr(const str[], chr) return -1; } -// by JGHG, adapted -// removes charstotrim number of charactes from stringtotrim's -// - beginning if fromleft is true -// - end if fromleft is false -// tested +/** + * Remove @charstotrim number of characters from @stringtotrim, + * either from the beginning or the end of the string. + * + * @param stringtotrim The string to be trimmed. + * @param charstostrim The number of characters to trim. + * @param fromleft If set to true, the string will be trimmer from the left. + * If false, it will be trimmed from the right. + * + * @noreturn + */ stock xs_strtrim(stringtotrim[], charstotrim, bool:fromleft = true) { if (charstotrim <= 0) @@ -744,12 +1065,20 @@ stock xs_strtrim(stringtotrim[], charstotrim, bool:fromleft = true) } } -// by xeroblood, adapted -// copies characters from oldmsg to newmsg, starting at start and ending at end (_includes_ end). -// terminates newmsg with 0 -// if outlen is positive, it specifies the maximal number of characters to be copied. -// otherwise, assumes that newmsg is at least end-start+1 characters long. -// tested +/** + * Copies characters from @oldmsg to @newmsg, starting at @start and ending + * at @end (includes the end character). + * + * @param oldmsg The string to copy from. + * @param newmsg The string to copy to. + * @param start Starting position of the @oldmsg string to copy from. + * @param end Ending position of the @oldmsg string to copy from. + * @param outlen If positive, specifies the maximum number of characters + * to be copied. Otherwise, the function assumes that + * newmsg is at least @end - @start + 1 characters long. + * + * @noreturn + */ stock xs_strmid(const oldmsg[], newmsg[], start, end, outlen=-1) { new len = strlen(oldmsg); @@ -769,9 +1098,18 @@ stock xs_strmid(const oldmsg[], newmsg[], start, end, outlen=-1) newmsg[j] = 0; } -// by xeroblood, adapted -// maxelems: maximal number of elements in output, elemsize: maximal size of one element -// tested +/** + * "Explodes" a string, breaking it at the @delimeter character and putting + * each exploded part into the @output array. + * + * @param input The input string to be exploded. + * @param output The output array of string where exploded string will be stored. + * @param delimeter The character to break the string at. + * @param maxelems Maximum amount of elements in @output. + * @param elemsize Maximum size of each string in the @output array. + * + * @return The number of strings successfully exploded. + */ stock xs_explode(const input[], output[][], delimiter, maxelems, elemsize) { new nIdx = 0; @@ -799,7 +1137,18 @@ stock xs_explode(const input[], output[][], delimiter, maxelems, elemsize) return nIdx; } -// returns number of cells written. +/** + * The opposite of xs_explode(). Takes an array of strings and puts them together + * in a single string, delimeted by the @delimeter character. + * + * @param output The string to store the impoded string into. + * @param outsize The size of the output buffer. + * @param delimeter The character to put between imploded strings. + * @param input The array of strings to implode. + * @param elemsnum The number of strings in the input array. + * + * @return The number of characters in the final output buffer. + */ stock xs_implode(output[], outsize, delimiter, const input[][], elemsnum) { new pos = 0; @@ -824,8 +1173,17 @@ stock xs_implode(output[], outsize, delimiter, const input[][], elemsnum) stock xs__replace_buf[XS_REPLACEBUF_SIZE]; -// Replace all occurencies of what in text with with -// Returns number of (also partially if trimmed by len) replaced items. + +/** + * Replaces all occurencies of @what in @text with @with. + * + * @param text The text to search in. + * @param len The maximum size of the @text buffer. + * @param what What to search for. + * @param with What to replace occurencies with. + * + * @return Returns the number of replaced items. + */ stock xs_replace(text[], len, const what[], const with[]) { new occur = 0; @@ -864,8 +1222,16 @@ stock xs_replace(text[], len, const what[], const with[]) return occur; } -// replaces all occurencies of what in text with with -// Returns number of replaced items. +/** + * Replaces all occurencies of @what character in @text with @with character. + * + * @param text The text to search in. + * @param len The maximum size of the @text buffer. + * @param what What character to search for. + * @param with What charactear to replace occurencies with. + * + * @return The number of replaced characters. + */ stock xs_replace_char(text[], len, what, with) { // let the xs_replace function do the work @@ -879,8 +1245,16 @@ stock xs_replace_char(text[], len, what, with) } /****** MISC FUNCS *******/ -// sets namestr to name of the command identified by cid -// half-tested + +/** + * Retrieves the name of a command identified by its ID. + * + * @param cid The command ID. + * @param namestr The buffer where to store command's name. + * @param namelen The maximum size of the output buffer. + * + * @noreturn + */ stock xs_concmd_name(cid, namestr[], namelen) { new dummy1; @@ -888,8 +1262,13 @@ stock xs_concmd_name(cid, namestr[], namelen) get_concmd(cid, namestr, namelen, dummy1, dummy2, 0, 0); } -// Checks whether there are at least num free visible slots -// half-tested +/** + * Checks whether there are at least @num free visible slots. + * + * @param num The number of slots to check. + * + * @return true if there are at least that many free, false otherwise. + */ stock bool:xs_freevisibleslots(num) { new maxplayers = get_cvar_num("sv_visiblemaxplayers"); @@ -899,9 +1278,13 @@ stock bool:xs_freevisibleslots(num) return (get_playersnum(1) <= maxplayers-num) ? true : false; } -// Returns biggest possible positive number stock xs__maxnum = 0; -// tested + +/** + * Returns the biggest possible positive number. + * + * @return The biggest possible positive number. + */ stock xs_get_maxnum() { if (!xs__maxnum) @@ -917,7 +1300,11 @@ stock xs_get_maxnum() return xs__maxnum; } -// tested +/** + * Returns the smallest possible negative number. + * + * @return The smallest possible negative number. + */ stock xs_get_minnum() { return xs_get_maxnum() + 1;