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

@@ -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)
+	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 */
+                                          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;
-}
+}

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
+ * Gives an item to a player.
- * is announced with proper message to all players. */
+ *
+ * @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:
+ * Sets (adds, removes) hit zones for a player.
- * 1   - generic
+ *
- * 2   - head
+ * @note This actually set rules of how any player can hit any other. Example:
- * 4   - chest
+ *       set_user_hitzones(id, target, 2);
- * 8   - stomach
+ *       makes @id be able to hit @target only in the head.
- * 16  - left arm
+ *
- * 32  - right arm
+ * @param index         Client index
- * 64  - left leg
+ * @param target        The target player
- * 128 - right leg */
+ * @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);

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, &timestamp);
 
-/* 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.
+ * "Touches" an entry in the vault, updating its timestamp.
- * Like the unix command "touch," it will create an empty key
+ * 
- *  if the value does not exist.
+ * @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);

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

plugins/include/sqlx.inc

@@ -30,33 +30,49 @@ enum Handle
 };
 
 /**
- * Creates a connection information tuple.
+ * Creates a connection information tuple. This tuple must be passed
- * This tuple must be passed into connection routines.
+ * 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 Freeing the tuple is not necessary, but is a good idea if you create
- * !!NOTE!! I have seen most people think that this connects to the DB.
+ *       many of them. You can cache these handles globally.
- *   Nowhere does it say this, and in fact it does not.  It only caches
+ * @note This does not connect to the DB; it only caches the connection information.
- *   the connection information, the host/user/pass/etc.
+ * 
- *
+ * @param host          Database host
- * The optional timeout parameter specifies how long connections should wait before
+ * @param user          Database user
- * giving up.  If 0, the default (which is undefined) is used.
+ * @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.
+ * @note 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.
+ * @note The change will remain until you call this function with another value.
- * This native does nothing in SQLite. 
+ * @note This native does nothing in SQLite. 
  *
  * Example: "utf8", "latin1"
  *
- * @param h					Database or connection tuple Handle.
+ * @param h             Database or connection tuple Handle.
- * @param charset			The character set string to change to.
+ * @param charset       The character set string to change to.
- * @return					True, if character set was changed, false otherwise.
+ * 
+ * @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 
+ * @param db            Database handle for localization, or Empty_Handle 
- *                          for when a handle is not available.
+ *                      for when a handle is not available.
- * @param buffer			Buffer to copy to.
+ * @param buffer        Buffer to copy to.
- * @param buflen			Maximum size of the buffer.
+ * @param buflen        Maximum size of the buffer.
- * @param string			String to backquote (should not overlap buffer).
+ * @param string        String to backquote (should not overlap buffer).
- * @return					Length of new string, or -1 on failure.
+ * 
+ * @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 
+ * @param db            Database handle for localization, or Empty_Handle 
- *                          for when a handle is not available.
+ *                      for when a handle is not available.
- * @param buffer			Buffer to copy to.
+ * @param buffer        Buffer to copy to.
- * @param buflen			Maximum size of the buffer.
+ * @param buflen        Maximum size of the buffer.
- * @param fmt				Format of string to backquote (should not overlap buffer).
+ * @param fmt           Format of string to backquote (should not overlap buffer).
- * @param ...				Format arguments.
+ * @param ...           Format arguments.
- * @return					Length of new string, or -1 on failure.
+ * 
+ * @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 
+ * @note The handler should look like:
- *  connection, however, the interface is more complicated and 
+ *       public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime)
- *  asynchronous.  Furthermore, a new connection/disconnection is 
+ *       failstate - One of the three TQUERY_ defines.
- *  made for each query to simplify driver support.
+ *       query     - Handle to the query, do not free it.
- * The handler should look like:
+ *       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 db_tuple      Tuple handle, returned from SQL_MakeDbTuple().
- * @param query - Handle to the query, do not free it.
+ * @param handler       A function to be called when the query finishes. It has to be public.
- * @param error - An error message, if any.
+ * @param query         The query string.
- * @param errnum - An error code, if any.
+ * @param data          Additional data array that will be passed to the handler function.
- * @param data - Data array you passed in.
+ * @param dataSize      The size of the additional data array. 
- * @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)
  *
- * Note! The handle you pass in is a DB Tuple, NOT an active connection!
+ * @noreturn
- * Note! The handle does not need to be freed.
+ * @error               Thread worker was unable to start.
- * Also note: This function is not guaranteed to be in another thread
+ *                      Invalid info tuple handle.
- *  (in fact - it's not).  You're seeing data "after the fact", 
+ *                      Handler function not found.
- *  and as such to execute another query you should run 
- *  SQL_ThreadQuery again with new data.
  */
 native SQL_ThreadQuery(Handle:db_tuple, const handler[], const query[], const data[]="", dataSize=0);
 
 
 /**
- * Executes a query.
+ * Executes an already prepared 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. 
- * NOTE: You can call this multiple times as long as its parent
+ *       Each time the result set from the previous call will be freed.
- *  connection is kept open.  Each time the result set will be freed
+ *
- *  from the previous call.
+ * @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,
+ * Checks whether there are more results to be read.
- *  0 otherwise.
+ *
+ * @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
+ * Tells whether a specific column in the current row is NULL or not.
- *  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.
+ * @note A successful query starts at the first result, so you should not call
- * Passing no extra params - return int
+ *       SQL_NextRow() first.
- * Passing one extra param - return float in 1st extra arg
+ * 
- * Passing two extra params - return string in 1st arg, max length in 2nd
+ * @note Example how to get different types of values:
- * Example:
+ *         new num = SQL_ReadResult(query, 0)
- *  new num = SQL_ReadResult(query, 0)
+ *         new Float:num2
- *  new Float:num2
+ *         new string[32]
- *  new str[32]
+ *         SQL_ReadResult(query, 1, num2)
- *  SQL_ReadResult(query, 1, num2)
+ *         SQL_ReadResult(query, 2, string, charsmax(string))
- *  SQL_ReadResult(query, 2, str, 31)
+ *
+ * @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.
+ * Retrieves the name of a column by its index.
- * Errors on a bad field number.
+ *
+ * @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. 
+ * Retrieves the instert ID of the latest INSERT query.
- * Returns 0 otherwise.
+ *
+ * @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 
+ * Sets driver affinity. You can use this to force a particular driver implementation.
- *  driver implementation.  This will automatically change all SQL
+ * This will automatically change all SQL natives in your plugin to be "bound" to
- *  natives in your plugin to be "bound" to the module in question.
+ * 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
+ * @note Using this while you have open handles to another database type will
- *  to handle different driver types at once, you should let this error pass.
+ *       cause problems. I.e., you cannot open a handle, switch affinity,
- * Note, that using this while you have open handles to another database 
+ *       then close the handle with a different driver.
- *  type will cause problems.  I.e., you cannot open a handle, switch
+ * @note Switching affinity is an O(n * m) operation, where n is the number of
- *  affinity, then close the handle with a different driver.
+ *       SQL natives and m is the number of used natives in total.
- * Switching affinity is an O(n*m) operation, where n is the number of
+ * @note Intuitive programmers will note that this causes problems for
- *  SQL natives and m is the number of used natives in total.
+ *       threaded queries. You will have to either force your script to work
- * Intuitive programmers will note that this causes problems for threaded queries.
+ *       under one affinity, or to pack the affinity type into the query data,
- *  You will have to either force your script to work under one affinity, or to 
+ *       check it against the current, then set the new affinity if necessary.
- *  pack the affinity type into the query data, check it against the current, then
+ *       Then, restore the old one for safety.
- *  set the new affinity if necessary.  Then, restore the old 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 
+ * @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 
+ *       queries in MySQL.  Nonetheless, it has the same effect of removing the last
- * result set.
+ *       result set.
  *
- * @param query		Query Handle.
+ * @param query         Query Handle.
- * @return			True on success, false on failure.
+ * 
+ * @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.
+ * This function can be used to find out if a table in a SQLite database exists.
- * (updated for newer API)
+ *
+ * @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];

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]);