From 5f278eee7badecb253c5f492b93435c96c8fc748 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 17 Feb 2015 15:24:14 +0100
Subject: [PATCH 01/10] amxmisc: Documentation updates and additions

---
 plugins/include/amxmisc.inc | 248 +++++++++++++++++++++++++++++-------
 1 file changed, 201 insertions(+), 47 deletions(-)

diff --git a/plugins/include/amxmisc.inc b/plugins/include/amxmisc.inc
index 289566dd..8c516f0b 100755
--- a/plugins/include/amxmisc.inc
+++ b/plugins/include/amxmisc.inc
@@ -16,12 +16,35 @@
 	#include <amxmodx>
 #endif
 
+/**
+ * Returns if the client has any admin flags set
+ *
+ * @param id    Client index
+ *
+ * @return      1 if client has any admin flags, 0 otherwise
+ */
 stock is_user_admin(id)
 {
 	new __flags = get_user_flags(id);
 	return (__flags > 0 && !(__flags & ADMIN_USER));
 }
 
+/**
+ * Returns if the user can execute the current command by checking the necessary
+ * admin flags and parameter count. Displays a denied access message to the user
+ * if missing privileges or a usage example if too few parameters are provided.
+ *
+ * @note This should be used inside of a command forward as it uses read_argc()
+ *       to check the parameter count.
+ *
+ * @param id            Client index
+ * @param level         Required admin flags
+ * @param cid           Command id
+ * @param num           Required number of parameters
+ * @param acesssilent   If true no denied access message will be printed
+ *
+ * @return              1 if access granted and parameters provided, 0 otherwise
+ */
 stock cmd_access(id, level, cid, num, bool:accesssilent = false)
 {
 	new has_access = 0;
@@ -64,6 +87,14 @@ stock cmd_access(id, level, cid, num, bool:accesssilent = false)
 	return 1;
 }
 
+/**
+ * Returns if the client has the specified admin flags.
+ *
+ * @param id        Client index
+ * @param level     Required admin flags
+ *
+ * @return          1 if client has the admin flags, 0 otherwise
+ */
 stock access(id, level)
 {
 	if (level == ADMIN_ADMIN)
@@ -78,18 +109,36 @@ stock access(id, level)
 	return (get_user_flags(id) & level);
 }
 
-/** 
- * Flags related to cmd_target:
- * 1 - obey immunity
- * 2 - allow yourself
- * 4 - must be alive
- * 8 - can't be bot
+/**
+ * cmd_target flags
  */
-#define CMDTARGET_OBEY_IMMUNITY (1<<0)
-#define CMDTARGET_ALLOW_SELF    (1<<1)
-#define CMDTARGET_ONLY_ALIVE    (1<<2)
-#define CMDTARGET_NO_BOTS       (1<<3)
+#define CMDTARGET_OBEY_IMMUNITY (1<<0) // Obey immunity
+#define CMDTARGET_ALLOW_SELF    (1<<1) // Allow self targeting
+#define CMDTARGET_ONLY_ALIVE    (1<<2) // Target must be alive
+#define CMDTARGET_NO_BOTS       (1<<3) // Target can't be a bot
 
+/**
+ * Processes a generic target pattern and tries to match it to a client based
+ * on filtering flags. If no unique target is found an appropriate message is
+ * displayed to the admin.
+ *
+ * @note The pattern is first matched case insensitively against client names.
+ *       If no match is found it is matched against client authids. If still no
+ *       match is found and the pattern starts with '#' it is finally matched
+ *       against client userids.
+ * @note Since client names are matched by substring the pattern can potentially
+ *       match multiple targets. In that case the function will return 0 and ask
+ *       the admin to provide a unique pattern.
+ * @note The filtering flags are applied after the pattern matching has
+ *       finished. That means the pattern has to be unique against all clients
+ *       on the server even if some of them are not eligible.
+ *
+ * @param id        Client index of admin performing an action
+ * @param arg       Target pattern
+ * @param flags     Filtering flags, see CMDTARGET_* constants above
+ *
+ * @return          Client index, or 0 if no or multiple clients matched
+ */
 stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY)
 {
 	new player = find_player("bl", arg);
@@ -145,12 +194,13 @@ stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY)
 }
 
 /**
- * Standard method to show activity to clients connected to the server.
- * This depends on the amx_show_activity cvar.  See documentation for more details.
+ * Standard method to show admin activity to clients connected to the server.
+ * This depends on the amx_show_activity cvar. See documentation for more details.
  *
- * @param id     The user id of the person doing the action.
- * @param name   The name of the person doing the action.
- * @param fmt    The format string to display.  Do not put the "ADMIN:" prefix in this.
+ * @param id     Client index performing the action
+ * @param name   Name of client performing the action
+ * @param fmt    Formatting rules
+ * @param ...    Variable number of formatting parameters
  *
  * @noreturn
  */
@@ -237,14 +287,14 @@ stock show_activity(id, const name[], const fmt[], any:...)
 }
 
 /**
- * Standard method to show activity to one single client.
- * This is useful for messages that get pieced together by many language keys.
- * This depends on the amx_show_activity cvar.  See documentation for more details.
+ * Standard method to show admin activity to a single client.
+ * This depends on the amx_show_activity cvar. See documentation for more details.
  *
- * @param idtarget   The user id of the person to display to.  0 is invalid.
- * @param idadmin    The user id of the person doing the action.
- * @param name       The name of the person doing the action.
- * @param fmt        The format string to display.  Do not put the "ADMIN:" prefix in this.
+ * @param idtarget  Client index to display message to
+ * @param id        Client index performing the action
+ * @param name      Name of client performing the action
+ * @param fmt       Formatting rules
+ * @param ...       Variable number of formatting parameters
  *
  * @noreturn
  */
@@ -254,7 +304,7 @@ stock show_activity_id(idtarget, idadmin, const name[], const fmt[], any:...)
 	{
 		return;
 	}
-	
+
 	static __amx_show_activity;
 	if (__amx_show_activity == 0)
 	{
@@ -437,6 +487,18 @@ stock show_activity_key(const KeyWithoutName[], const KeyWithName[], const ___Ad
 	}
 }
 
+/**
+ * Returns if the mod running on the server supports colored menus.
+ *
+ * @note The full list of mods supporting colored menus:
+ *       Counter-Strike, Counter-Strike: Condition Zero, Deathmatch Classic,
+ *       Day of Defeat, Team Fortress Classic and Half-Life: Deathmatch.
+ * @note Since this is a stock and compiled into the plugin, the list of
+ *       supported mods will not update and require recompilation of the plugin
+ *       if the list ever changed.
+ *
+ * @return  1 if colored menus are supported, 0 otherwise
+ */
 stock colored_menus()
 {
 	static ColoredMenus = -1;
@@ -465,6 +527,11 @@ stock colored_menus()
 	return ColoredMenus;
 }
 
+/**
+ * Returns if the mod running on the server is a version of Counter-Strike.
+ *
+ * @return  1 if mod is Counter-Strike, 0 otherwise
+ */
 stock cstrike_running()
 {
 	new mod_name[32];
@@ -473,6 +540,13 @@ stock cstrike_running()
 	return (equal(mod_name, "cstrike") || equal(mod_name, "czero") || equal(mod_name, "csv15") || equal(mod_name, "cs13"));
 }
 
+/**
+ * Returns if the server is running a specific mod.
+ *
+ * @param mod   Mod name to check for
+ *
+ * @return      1 if mod name matches, 0 otherwise
+ */
 stock is_running(const mod[])
 {
 	new mod_name[32];
@@ -481,42 +555,92 @@ stock is_running(const mod[])
 	return equal(mod_name, mod);
 }
 
+/**
+ * Retrieves the path to the AMXX base directory.
+ *
+ * @param name  Buffer to copy path to
+ * @param len   Maximum buffer size
+ *
+ * @return      Number of cells written to buffer
+ */
 stock get_basedir(name[], len)
 {
 	return get_localinfo("amxx_basedir", name, len);
 }
 
+/**
+ * Retrieves the path to the AMXX configs directory.
+ *
+ * @param name  Buffer to copy path to
+ * @param len   Maximum buffer size
+ *
+ * @return      Number of cells written to buffer
+ */
 stock get_configsdir(name[], len)
 {
 	return get_localinfo("amxx_configsdir", name, len);
 }
 
+/**
+ * Retrieves the path to the AMXX data directory.
+ *
+ * @param name  Buffer to copy path to
+ * @param len   Maximum buffer size
+ *
+ * @return      Number of cells written to buffer
+ */
 stock get_datadir(name[], len)
 {
 	return get_localinfo("amxx_datadir", name, len);
 }
 
+/**
+ * Provides a shorthand to register a working menu.
+ *
+ * @note Combines the necessary calls to register_menuid() and
+ *       register_menucmd() into a single function.
+ *
+ * @param title     Menu name
+ * @param keys      Key flags
+ * @param function  Callback function
+ * @param outside   Catch menus outside the calling plugin
+ *
+ * @noreturn
+ * @error           If an invalid callback function is specified, an error will
+ *                  be thrown.
+ */
 stock register_menu(const title[], keys, const function[], outside = 0)
 {
 	register_menucmd(register_menuid(title, outside), keys, function);
 }
 
 /**
- * Backwards Compatibility
- * don't use it!
+ * Alias to get_configsdir provided for backwards compatibility. Originally
+ * intended to retrieve the AMXX custom directory.
+ *
+ * @deprecated Should not be used as the concept of a custom directory does no
+ *             longer exists in AMXX.
+ *
+ * @param name  Buffer to copy path to
+ * @param len   Maximum buffer size
+ *
+ * @return      Number of cells written to buffer
  */
+#pragma deprecated The concept of a custom directory no longer exists in AMXX. Do not use.
 stock get_customdir(name[], len)
 {
-	return get_localinfo("amxx_configsdir", name, len);
+	return get_configsdir(name, len);
 }
 
 /**
- * Add a menu item to Menus Front-End plugin ("amxmodmenu").
+ * Adds a menu item/command to the admin menu (amxmodmenu) handled by the
+ * "Menus Front-End" plugin, if it is loaded.
  *
- * @param MENU_TEXT     Text that will be shown for this item in menu.
- * @param MENU_CMD      Command that should be executed to start menu.
- * @param MENU_ACCESS   Access required for menu.
- * @param MENU_PLUGIN   The exact case-insensitive name of plugin holding the menu command.
+ * @param MENU_TEXT     Item text that will be displayed in the menu
+ * @param MENU_CMD      Command that will be executed on the client
+ * @param MENU_ACCESS   Admin access required for menu command
+ * @param MENU_PLUGIN   Case-insensitive name or filename of plugin providing
+ *                      the menu command
  *
  * @noreturn
  */
@@ -526,12 +650,15 @@ stock AddMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const
 }
 
 /**
- * Add a menu item to "amx_menu", that should also be accessible by non-admins.
+ * Adds a menu item/command to the client menu (amx_menu) handled by the
+ * "Menus Front-End" plugin, if it is loaded. Items should be accessible by
+ * non-admins.
  *
- * @param MENU_TEXT     Text that will be shown for this item in menu.
- * @param MENU_CMD      Command that should be executed to start menu.
- * @param MENU_ACCESS   Access required for menu.
- * @param MENU_PLUGIN   The exact case-insensitive name of plugin holding the menu command.
+ * @param MENU_TEXT     Item text that will be displayed in the menu
+ * @param MENU_CMD      Command that will be executed on the client
+ * @param MENU_ACCESS   Admin access required for menu command
+ * @param MENU_PLUGIN   Case-insensitive name or filename of plugin providing
+ *                      the menu command
  *
  * @noreturn
  */
@@ -541,7 +668,17 @@ stock AddClientMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS,
 }
 
 /**
- * Internal function used by above stocks.
+ * Helper function used by AddMenuItem() and AddClientMenuItem()
+ *
+ * @param MENU_TEXT             Item text that will be displayed in the menu
+ * @param MENU_CMD              Command that will be executed on the client
+ * @param MENU_ACCESS           Admin access required for menu command
+ * @param MENU_PLUGIN           Case-insensitive name or filename of plugin
+ *                              providing the menu command
+ * @param ADD_TO_CLIENT_MENU    If true adds command to client menu, false adds
+ *                              to admin menu
+ *
+ * @noreturn
  */
 stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const MENU_PLUGIN[], const bool:ADD_TO_CLIENT_MENU)
 {
@@ -557,7 +694,7 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c
 
 	new status = callfunc_begin(ADD_TO_CLIENT_MENU ? "AddClientMenu" : "AddMenu", filename);
 	new bool:failed = true;
-	switch (status) 
+	switch (status)
 	{
 		case 1:
 		{
@@ -592,11 +729,28 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c
 	callfunc_end();
 }
 
+/**
+ * Computes an offset from a given value while constraining it between the
+ * specified bounds, rolling over if necessary.
+ *
+ * @note Example: The range is 1-5 and the base value (seed) is 3, the offset
+ *       that the value should be moved by is also 3. Offsetting the value by 3
+ *       would result in 6, but it is to be constrained between 1 and 5. With
+ *       clamp() this would result in 5, but this function rolls the value over
+ *       and returns 1 instead.
+ *
+ * @param low       Lower bound
+ * @param high      Higher bound
+ * @param seed      Base value
+ * @param offset    Offset to move
+ *
+ * @return          Computed offset value between specified bounds
+ */
 stock constraint_offset(low, high, seed, offset)
 {
 	new numElements = high - low + 1;
 	offset += seed - low;
-   
+
 	if (offset >= 0)
 	{
 		return low + (offset % numElements);
@@ -610,25 +764,25 @@ stock constraint_offset(low, high, seed, offset)
 }
 
 /**
- * Tells if the user has ANY of the provided flags.
+ * Returns if the client has any of the specified admin flags.
  *
  * @param id      Client index
  * @param flags   Flag string
  *
- * @return        1 if the user has ANY of the provided flags, 0 otherwise
+ * @return        1 if the user has any of the specified flags, 0 otherwise
  */
 stock has_flag(id, const flags[])
 {
 	return (get_user_flags(id) & read_flags(flags));
 }
 
- /**
- * Tells if the user has ALL of the provided flags.
+/**
+ * Returns if the client has all of the specified admin flags.
  *
  * @param id      Client index
  * @param flags   Flag string
  *
- * @return        1 if the user has ALL of the provided flags, 0 otherwise
+ * @return        1 if the user has all of the specified flags, 0 otherwise
  */
 stock has_all_flags(id, const flags[])
 {
@@ -637,11 +791,11 @@ stock has_all_flags(id, const flags[])
 }
 
 /**
- * Resets a client's menu.
+ * Resets the client's menu.
  *
- * @note This is just a wrapper around show_menu for the sake of readability.
+ * @note This is a wrapper around show_menu() for the sake of readability.
  *
- * @param index     Client to reset menu to, use 0 to reset to all clients
+ * @param index     Client to reset menu of, 0 to reset all clients
  *
  * @noreturn
  */

From 9eb0eaf6a6a0312296c856b9b3586595bd8022a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 17 Feb 2015 17:51:56 +0100
Subject: [PATCH 02/10] core: Add documentation

---
 plugins/include/core.inc | 176 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 168 insertions(+), 8 deletions(-)

diff --git a/plugins/include/core.inc b/plugins/include/core.inc
index 039954a0..7b8ba5f9 100755
--- a/plugins/include/core.inc
+++ b/plugins/include/core.inc
@@ -10,33 +10,193 @@
 #endif
 #define _core_included
 
+/**
+ * Returns the free memory space available to the plugin.
+ *
+ * @note This is a debugging function that is not intended for general plugin
+ *       use.
+ *
+ * @return  Free memory space in bytes
+ */
 native heapspace();
 
+/**
+ * Returns the function index of a public function declared in the plugin.
+ *
+ * @param name  Function name
+ *
+ * @return      Function index > 0 on success, -1 if function was not found
+ * @error       If the function name is too long (longer than 63 characters)
+ *              an error will be thrown.
+ */
 native funcidx(const name[]);
 
+/**
+ * Returns the number of arguments passed into the currently executed function.
+ *
+ * @return  Number of arguments passed
+ */
 native numargs();
-native getarg(arg, index=0);
-native setarg(arg, index=0, value);
 
+/**
+ * Retrieves an argument value passed into the currently executed function.
+ *
+ * @param arg       Argument index
+ * @param index     Index to retrieve from the argument (for arrays and strings)
+ *
+ * @return          Argument value at given index
+ */
+native getarg(arg, index = 0);
+
+/**
+ * Sets the value of an argument passed into the currently executed function.
+ *
+ * @note This is not equal to assigning a new value to a by-reference argument.
+ *
+ * @param arg       Argument index
+ * @param index     Index to set in the argument (for arrays and strings)
+ */
+native setarg(arg, index = 0, value);
+
+/**
+ * Converts a character to lowercase.
+ *
+ * @note This is not UTF8 or locale-safe.
+ *
+ * @param c     Character to convert
+ *
+ * @return      Converted character
+ */
 native tolower(c);
+
+/**
+ * Converts a character to uppercase.
+ *
+ * @note This is not UTF8 or locale-safe.
+ *
+ * @param c     Character to convert
+ *
+ * @return      Converted character
+ */
 native toupper(c);
+
+/**
+ * Swaps the bytes of a value (the lowest byte becomes the highest byte).
+ *
+ * @param c     Value to swap
+ *
+ * @return      Byte-swapped value
+ */
 native swapchars(c);
 
+/**
+ * Returns a random number between 0 and a specified upper bound.
+ *
+ * @param max   Exclusive upper bound
+ *
+ * @return      Random value
+ */
 native random(max);
 
+/**
+ * Returns the smaller of two provided values.
+ *
+ * @param value1    Value one
+ * @param value2    Value two
+ *
+ * @return          Smaller of the two values
+ */
 native min(value1, value2);
-native max(value1, value2);
-native clamp(value, min=cellmin, max=cellmax);
 
+/**
+ * Returns the bigger of two provided values.
+ *
+ * @param value1    Value one
+ * @param value2    Value two
+ *
+ * @return          Bigger of the two values
+ */
+native max(value1, value2);
+
+/**
+ * Limits a provided value between two specified bounds.
+ *
+ * @param value     Value to clamp
+ * @param min       Lower bound
+ * @param max       Upper bound
+ *
+ * @return          The value if it is between the lower and upper bound, min if
+ *                  value is below, max if it is above the specified bounds.
+ */
+native clamp(value, min = cellmin, max = cellmax);
+
+/**
+ * Returns a value raised to a specified exponent.
+ *
+ * @param value     Value
+ * @param exponent  Exponent to raise value to
+ *
+ * @return          Value to the power of exponent
+ */
 native power(value, exponent);
+
+/**
+ * Returns the approximated square root of a value.
+ *
+ * @note This uses a simple successice approximation algorithm (continuously
+ *       dividing the value) and only deals with integers, this makes it very
+ *       imprecise.
+ *
+ * @param value     Value
+ *
+ * @return          Square root of the value
+ */
 native sqroot(value);
 
-native time(&hour=0,&minute=0,&second=0);
-native date(&year=0,&month=0,&day=0);
+/**
+ * Retrieves the current time in hours, minutes and seconds.
+ *
+ * @param hour      Variable to store hours in
+ * @param minute    Variable to store minutes in
+ * @param second    Variable to store seconds in
+ *
+ * @return          Unix timestamp
+ */
+native time(&hour = 0, &minute = 0, &second = 0);
 
-native tickcount(&granularity=0);
+/**
+ * Retrieves the current date in year, month and day.
+ *
+ * @param hour      Variable to store year in
+ * @param minute    Variable to store month in
+ * @param second    Variable to store day in
+ *
+ * @noreturn
+ */
+native date(&year = 0, &month = 0, &day = 0);
 
+/**
+ * Returns the elapsed CPU seconds.
+ *
+ * @note This is a debugging function that is not intended for general plugin
+ *       use.
+ * @note This uses the C clock() function internally and comes with all its
+ *       drawbacks attached.
+ *
+ * @param granularity   Unused
+ *
+ * @return              Number of CPU seconds elapsed
+ */
+native tickcount(&granularity = 0);
+
+/**
+ * Returns the absolute value of a number.
+ *
+ * @param x     Integral value
+ *
+ * @return      Absolute value of x (x if it is greater than 0, -x otherwise)
+ */
 stock abs(x)
 {
-	return x > 0 ? x : -x;
+    return x > 0 ? x : -x;
 }

From ae86152282fbfd0a4060e41d7532463f351fa242 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 17 Feb 2015 15:25:53 +0100
Subject: [PATCH 03/10] cellarray/celltrie/cellstack: Documentation fixes and
 consistency updates

---
 plugins/include/cellarray.inc |  30 +++--
 plugins/include/cellstack.inc | 138 ++++++++++---------
 plugins/include/celltrie.inc  | 244 ++++++++++++++++++++--------------
 3 files changed, 232 insertions(+), 180 deletions(-)

diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc
index 3c52a233..261c4707 100644
--- a/plugins/include/cellarray.inc
+++ b/plugins/include/cellarray.inc
@@ -63,7 +63,9 @@ stock ByteCountToCells(size)
  *                      number of items. The items are not valid to read or set
  *                      until they have actually been pushed into the array.
  *
- * @return              Handle to the array.
+ * @return              New array handle, which must be freed via ArrayDestroy()
+ * @error               If an invalid cellsize is provided an error will be
+ * 	                    thrown.
  */
 native Array:ArrayCreate(cellsize = 1, reserved = 32);
 
@@ -431,7 +433,7 @@ native DoNotUse:ArrayGetStringHandle(Array:which, item);
  *
  * @param which         Array to destroy
  *
- * @return              1 if the array was destroyed, 0 if nothing had to be
+ * @return              1 if the Array was destroyed, 0 if nothing had to be
  *                      destroyed (invalid handle)
  */
 native ArrayDestroy(&Array:which);
@@ -444,10 +446,10 @@ native ArrayDestroy(&Array:which);
  *
  * public MySortFunc(Array:array, item1, item2, const data[], data_size)
  *
- *  array           - Array handle in its current un-sorted state
- *  item1, item2    - Current item pair being compared
- *  data[]          - Extra data array passed to the sort func
- *  data_size       - Size of extra data
+ *   array           - Array handle in its current un-sorted state
+ *   item1, item2    - Current item pair being compared
+ *   data[]          - Extra data array passed to the sort func
+ *   data_size       - Size of extra data
  *
  * @note The comparison function should return:
  *         -1 if item1 should go before item2
@@ -485,20 +487,20 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0);
  *
  * public MySortFunc(Array:array, elem1, elem2, const data[], data_size)
  *
- *  array           - Array handle in its current un-sorted state
- *  elem1, elem2    - Current element pair being compared
- *  data[]          - Extra data array passed to the sort func
- *  data_size       - Size of extra data
+ *   array           - Array handle in its current un-sorted state
+ *   elem1, elem2    - Current element pair being compared
+ *   data[]          - Extra data array passed to the sort func
+ *   data_size       - Size of extra data
  *
  * @note For Arrays with a cellsize larger than 1 (used for storing arrays and
  *       strings), the function is called in the following manner:
  *
  * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size)
  *
- *  array               - Array handle in its current un-sorted state
- *  elem1[], elem2[]    - Current element pair being compared
- *  data[]              - Extra data array passed to the sort func
- *  data_size           - Size of extra data
+ *   array               - Array handle in its current un-sorted state
+ *   elem1[], elem2[]    - Current element pair being compared
+ *   data[]              - Extra data array passed to the sort func
+ *   data_size           - Size of extra data
  *
  *
  * @note The comparison function should return:
diff --git a/plugins/include/cellstack.inc b/plugins/include/cellstack.inc
index 81043d76..15e8567f 100644
--- a/plugins/include/cellstack.inc
+++ b/plugins/include/cellstack.inc
@@ -12,131 +12,139 @@
 #endif
 #define _cellstack_included
 
+/**
+ * Stack tag declaration
+ *
+ * @note Plugins are responsible for freeing all Stack handles they acquire.
+ *       Failing to free handles will result in the plugin and AMXX leaking
+ *       memory.
+ */
 enum Stack
 {
 	Invalid_Stack = 0
 };
 
 /**
- * Creates a stack structure.  A stack is a LIFO (last in, first out)
- * vector (array) of items.  It has O(1) insertion and O(1) removal.
+ * Creates a stack structure. A stack is a LIFO (last in, first out) vector of
+ * of items. It has O(1) insertion and O(1) removal.
  *
- * Stacks have two operations: Push (adding an item) and Pop (removes
- * items in reverse-push order).
+ * @note Stacks provide only two operations: Push (adding an item to the top)
+ * 		 and Pop (remove an item from the top, in reverse-push order).
+ * @note The contents of the stack are uniform; i.e. storing a string and then
+ *       retrieving it as an integer is NOT the same as str_to_num()!
+ * @note The "blocksize" determines how many cells each stack slot has, it can
+ *       not be changed after creation.
  *
- * The contents of the stack are uniform; i.e. storing a string and then
- * retrieving it as an integer is NOT the same as StringToInt()!
+ * @param blocksize     The number of cells each entry in the stack can hold
  *
- * The "blocksize" determines how many cells each slot has; it cannot
- * be changed after creation.
- *
- * @param blocksize     The number of cells each entry in the stack can
- *                      hold.  For example, 32 cells is equivalent to:
- *                      new Array[X][32]
- *
- * @return              New stack Handle.
- * @error               Invalid block size.
+ * @return              New stack Handle, which must be freed via DestroyStack()
+ * @error               If an invalid blocksize is provided an error will be
+ *                      thrown.
  */
 native Stack:CreateStack(blocksize = 1);
 
 /**
  * Pushes a value onto the end of the stack, adding a new index.
  *
- * This may safely be used even if the stack has a blocksize
- * greater than 1.
+ * @note This may safely be used even if the stack has a blocksize greater than
+ *       1.
  *
- * @param handle        Stack handle.
- * @param value         Value to push.
+ * @param handle    Stack handle
+ * @param value     Value to push
  *
  * @noreturn
- * @error               Invalid handle or out of memory.
+ * @error           If an invalid handle is provided or the resizing
+ *                  operation runs out of memory, an error will be thrown.
  */
 native PushStackCell(Stack:handle, any:value);
 
 /**
- * Pushes a string onto the end of a stack, truncating it if it is
- * too big.
+ * Pushes a string onto the end of a stack, truncating it if it is too long.
  *
- * @param handle        Stack handle.
- * @param value         String to push.
+ * @param handle    Stack handle
+ * @param value     String to push
  *
  * @noreturn
- * @error               Invalid handle or out of memory.
+ * @error           If an invalid handle is provided or the resizing
+ *                  operation runs out of memory, an error will be thrown.
  */
 native PushStackString(Stack:handle, const value[]);
 
 /**
- * Pushes an array of cells onto the end of a stack.  The cells
- * are pushed as a block (i.e. the entire array takes up one stack slot),
- * rather than pushing each cell individually.
+ * Pushes an array of cells onto the end of a stack. The cells are pushed as a
+ * block (i.e. the entire array takes up one stack slot), rather than pushing
+ * each cell individually.
+ *
+ * @param handle    Stack handle
+ * @param values    Block of values to copy
+ * @param size      If not set, the number of elements copied from the array
+ *                  will be equal to the blocksize, if set higher than the
+ *                  blocksize, the operation will be truncated,
  *
- * @param handle        Stack handle.
- * @param values        Block of values to copy.
- * @param size          If not set, the number of elements copied from the array
- *                      will be equal to the blocksize.  If set higher than the
- *                      blocksize, the operation will be truncated.
  * @noreturn
- * @error               Invalid handle or out of memory.
+ * @error           If an invalid handle is provided or the resizing
+ *                  operation runs out of memory, an error will be thrown.
  */
 native PushStackArray(Stack:handle, const any:values[], size= -1);
 
 /**
  * Pops a cell value from a stack.
  *
- * @param handle        Stack handle.
- * @param value         Variable to store the value.
- * @param block         Optionally specify which block to read from
- *                      (useful if the blocksize > 0).
- * @param asChar        Optionally read as a byte instead of a cell.
+ * @param handle    Stack handle
+ * @param value     Variable to store the value in
+ * @param block     Optionally specify which block to read from (useful if the
+ *                  blocksize is > 0)
+ * @param asChar    Optionally read as a byte instead of a cell
  *
- * @return              True on success, false if the stack is empty.
- * @error               Invalid handle, Invalid block or Invalid byte.
+ * @return          True on success, false if the stack is empty.
+ * @error           If an invalid handle, invalid block or invalid byte is
+ *                  provided, an error will be thrown.
  */
 native bool:PopStackCell(Stack:handle, &any:value, block = 0, bool:asChar = false);
 
 /**
  * Pops a string value from a stack.
  *
- * @param handle        Stack handle.
- * @param buffer        Buffer to store string.
- * @param maxlength     Maximum size of the buffer.
- * @param written       Number of characters copied.
+ * @param handle        Stack handle
+ * @param buffer        Buffer to copy string to
+ * @param maxlength     Maximum size of the buffer
+ * @param written       Variable to store number of characters copied to
  *
- * @return              True on success, false if the stack is empty.
- * @error               Invalid handle.
+ * @return              True on success, false if the stack is empty
+ * @error               If an invalid handle is provided an error will be thrown.
  */
 native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0);
 
 /**
  * Pops an array of cells from a stack.
  *
- * @param handle        Stack handle.
- * @param buffer        Buffer to store the array in.
- * @param size          If not set, assumes the buffer size is equal to the
- *                      blocksize.  Otherwise, the size passed is used.
+ * @param handle    Stack handle
+ * @param buffer    Array to copy value to
+ * @param size      Size of buffer, if not set (-1) assumes the size is equal to
+ *                  the stack blocksize
  *
- * @return              True on success, false if the stack is empty.
- * @error               Invalid handle.
+ * @return          True on success, false if the stack is empty
+ * @error           If an invalid handle is provided an error will be thrown.
  */
 native bool:PopStackArray(Stack:handle, any:buffer[], size = -1);
 
 /**
- * Checks if a stack is empty.
+ * Returns if a stack is empty.
  *
- * @param handle        Stack handle.
+ * @param handle    Stack handle
  *
- * @return              True if empty, false if not empty.
- * @error               Invalid handle.
+ * @return          True if empty, false if not empty
+ * @error           If an invalid handle is provided an error will be thrown.
  */
 native bool:IsStackEmpty(Stack:handle);
 
 /**
  * Pops a value off a stack, ignoring it completely.
  *
- * @param handle        Stack handle.
+ * @param handle    Stack handle
  *
- * @return              True if something was popped, false otherwise.
- * @error               Invalid handle.
+ * @return          True if a value was popped, false if stack is empty
+ * @error           If an invalid handle is provided an error will be thrown.
  */
 stock PopStack(Stack:handle)
 {
@@ -145,10 +153,14 @@ stock PopStack(Stack:handle)
 }
 
 /**
- * Destroys the stack, and resets the handle to 0 to prevent accidental usage after it is destroyed.
+ * Destroys a stack and frees its memory.
  *
- * @param which         The stack to destroy.
+ * @note The function automatically sets the variable passed to it to 0 to aid
+ *       in preventing accidental usage after destroy.
  *
- * @noreturn
+ * @param handle    Stack to destroy
+ *
+ * @return          1 if the Stack was destroyed, 0 if nothing had to be
+ *                  destroyed (invalid handle)
  */
 native DestroyStack(&Stack:handle);
diff --git a/plugins/include/celltrie.inc b/plugins/include/celltrie.inc
index 9a05a4b2..729be00c 100644
--- a/plugins/include/celltrie.inc
+++ b/plugins/include/celltrie.inc
@@ -8,180 +8,213 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _celltrie_included
-	#endinput
+    #endinput
 #endif
 #define _celltrie_included
 
+/**
+ * Hash map tag declaration
+ *
+ * @note The word "Trie" in this API is historical. As of AMX Mod X 1.8.3,
+ *       tries have been internally replaced with hash tables, which have O(1)
+ *       insertion time instead of O(n).
+ * @note Plugins are responsible for freeing all Trie handles they acquire.
+ *       Failing to free handles will result in the plugin and AMXX leaking
+ *       memory.
+ */
 enum Trie
 {
 	Invalid_Trie = 0
 };
 
+/**
+ * Hash map snapshot tag declaration
+ *
+ * @note Plugins are responsible for freeing all Snapshot handles they acquire.
+ *       Failing to free handles will result in the plugin and AMXX leaking
+ *       memory.
+ */
 enum Snapshot
 {
 	Invalid_Snapshot = 0
 };
 
 /**
- * Creates a hash map. A hash map is a container that can map strings (called
- * "keys") to arbitrary values (cells, arrays, or strings). Keys in a hash map
- * are unique. That is, there is at most one entry in the map for a given key.
+ * Creates a hash map. A hash map is a container that maps strings (called keys)
+ * to arbitrary values (cells, arrays or strings).
  *
- * Insertion, deletion, and lookup in a hash map are all considered to be fast
- * operations, amortized to O(1), or constant time.
+ * @note Keys in a hash map are unique so there is no more than one entry in the
+ *       map for any given key.
+ * @note Insertion, deletion, and lookup in a hash map are all considered to be
+ *       fast operations, amortized to O(1), or constant time.
  *
- * The word "Trie" in this API is historical. As of AMX Mod X 1.8.3, tries have
- * been internally replaced with hash tables, which have O(1) insertion time
- * instead of O(n).
- *
- * @return 			New Map handle, which must be freed via TrieDestroy().
+ * @return  New Map handle, which must be freed via TrieDestroy()
  */
 native Trie:TrieCreate();
 
 /**
  * Clears all entries from a Map.
  *
- * @param handle	Map handle.
+ * @param handle    Map handle
  *
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
+ * @noreturn
  */
 native TrieClear(Trie:handle);
 
 /**
- * Sets a value in a hash map, either inserting a new entry or replacing an old one.
+ * Sets a cell value in a hash map, either inserting a new entry or replacing
+ * an old one.
  *
- * @param handle	Map handle.
- * @param key		Key string.
- * @param value		Value to store at this key.
- * @param replace	If false, operation will fail if the key is already set.
+ * @param handle    Map handle
+ * @param key       Key string
+ * @param value     Value to store
+ * @param replace   If false the operation will fail if the key is already set
  *
- * @return			True on success, false on failure.
- * @error			Invalid handle.
+ * @return          1 on success, 0 otherwise
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native TrieSetCell(Trie:handle, const key[], any:value, bool:replace = true);
 
 /**
- * Sets a string value in a Map, either inserting a new entry or replacing an old one.
+ * Sets a string value in a hash map, either inserting a new entry or replacing
+ * an old one.
  *
- * @param handle	Map handle.
- * @param key		Key string.
- * @param value		String to store.
- * @param replace	If false, operation will fail if the key is already set.
+ * @param handle    Map handle
+ * @param key       Key string
+ * @param value     String to store
+ * @param replace   If false the operation will fail if the key is already set
  *
- * @return			True on success, false on failure.
- * @error			Invalid handle.
+ * @return          1 on success, 0 otherwise
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native TrieSetString(Trie:handle, const key[], const value[], bool:replace = true);
 
 /**
- * Sets an array value in a Map, either inserting a new entry or replacing an old one.
+ * Sets an array value in a hash map, either inserting a new entry or replacing
+ * an old one.
  *
- * @param handle	Map handle.
- * @param key		Key string.
- * @param buffer	Array to store.
- * @param size		Number of items in the array.
- * @param replace	If false, operation will fail if the key is already set.
+ * @param handle    Map handle
+ * @param key       Key string
+ * @param buffer    Array to store
+ * @param size      Array size
+ * @param replace   If false the operation will fail if the key is already set
  *
- * @return			True on success, false on failure.
- * @error			Invalid handle.
- *					Invalid array size.
+ * @return          1 on success, 0 otherwise
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown. or invalid array size
  */
 native TrieSetArray(Trie:handle, const key[], const any:buffer[], size, bool:replace = true);
 
 /**
- * Retrieves a value in a Map.
+ * Retrieves a cell value from a hash map.
  *
- * @param handle	Map handle.
- * @param key		Key string.
- * @param value		Variable to store value.
- * @return			True on success.  False if the key is not set, or the key is set
- *					as an array or string (not a value).
- * @error			Invalid handle.
+ * @param handle    Map handle
+ * @param key       Key string
+ * @param value     Variable to store value to
+ *
+ * @return          True on success, false if either the key is not set or the
+ *                  value type does not match (value is string or array)
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native bool:TrieGetCell(Trie:handle, const key[], &any:value);
 
 /**
- * Retrieves a string in a Map.
+ * Retrieves a string from a hash map.
  *
- * @param handle		Map handle.
- * @param key			Key string.
- * @param output		Buffer to store value.
- * @param outputsize	Maximum size of string buffer.
- * @param size			Optional parameter to store the number of bytes written to the buffer.
+ * @param handle        Map handle
+ * @param key           Key string
+ * @param output        Buffer to copy the value to
+ * @param outputsize    Maximum size of buffer
+ * @param size          Optional variable to store the number of cells written
+ *                      to the buffer in
  *
- * @return				True on success.  False if the key is not set, or the key is set
- *						as a value or array (not a string).
- * @error				Invalid handle.
- *						Invalid buffer size.
+ * @return              True on success, false if either the key is not set or
+ *                      the value type does not match (value is cell or array)
+ * @error               If an invalid handle is provided an error will be
+ *                      thrown.
  */
 native bool:TrieGetString(Trie:handle, const key[], output[], outputsize, &size = 0);
 
 /**
- * Retrieves an array in a Map.
+ * Retrieves a string from a hash map.
  *
- * @param handle		Map handle.
- * @param key			Key string.
- * @param output		Buffer to store array.
- * @param outputsize	Maximum size of array buffer.
- * @param size			Optional parameter to store the number of elements written to the buffer.
+ * @param handle        Map handle
+ * @param key           Key string
+ * @param output        Array to copy the value to
+ * @param outputsize    Maximum size of array
+ * @param size          Optional variable to store the number of cells written
+ *                      to the array in
  *
- * @return				True on success.  False if the key is not set, or the key is set
- *						as a value or string (not an array).
- * @error				Invalid handle.
- *						Invalid array size.
+ * @return              True on success, false if either the key is not set or
+ *                      the value type does not match (value is cell or string)
+ * @error               If an invalid handle or array size is provided an error
+ *                      will be thrown.
  */
 native bool:TrieGetArray(Trie:handle, const key[], any:output[], outputsize, &size = 0);
 
 /**
- * Removes a key entry from a Map.
+ * Removes an entry from a hash map.
  *
- * @param handle	Map handle.
- * @param key		Key string.
+ * @param handle    Map handle
+ * @param key       Key string
  *
- * @return			True on success, false if the value was never set.
- * @error			Invalid handle.
+ * @return          True on success, false if the key was never set
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native bool:TrieDeleteKey(Trie:handle, const key[]);
 
 /**
- * Checks a key entry existence from a Map.
+ * Checks a hash map for the existence of an entry.
  *
- * @param handle	Map handle.
- * @param key		Key string.
+ * @param handle    Map handle
+ * @param key       Key string
  *
- * @return			True on success, false if the value was never set.
- * @error			Invalid handle.
+ * @return          True if the key is set, false otherwise
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native bool:TrieKeyExists(Trie:handle, const key[]);
 
 /**
- * Destroys a Map.
+ * Destroys a hash map and frees its memory.
  *
- * @param handle	Map handle.
+ * @note The function automatically sets the variable passed to it to 0 to aid
+ *       in preventing accidental usage after destroy.
  *
- * @return			True on success, false if the value was never set.
- * @error			Invalid handle.
+ * @param handle    Map handle
+ *
+ * @return          1 on success, 0 if an invalid handle was passed in
  */
 native TrieDestroy(&Trie:handle);
 
 /**
- * Retrieves the number of elements in a map.
+ * Returns the number of entries in a hash map.
  *
- * @param handle	Map handle.
+ * @param handle    Map handle
  *
- * @return			Number of elements in the trie.
- * @error			Invalid handle.
+ * @return          Number of elements in the hash map
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native TrieGetSize(Trie:handle);
 
 /**
- * Creates a snapshot of all keys in the map. If the map is changed after this
- * call, the changes are not reflected in the snapshot. Keys are not sorted.
+ * Creates a snapshot of all keys in a hash map. If the map is changed
+ * afterwards,  the changes are not reflected in the snapshot.
+ * Keys are not sorted.
  *
- * @param handle    Map handle.
+ * @param handle    Map handle
  *
- * @return			New map snapshot handle, which must be freed via TrieSnapshotDestroy().
- * @error			Invalid handle.
+ * @return          New map snapshot handle, which must be freed via
+ *                  TrieSnapshotDestroy()
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native Snapshot:TrieSnapshotCreate(Trie:handle);
 
@@ -190,10 +223,11 @@ native Snapshot:TrieSnapshotCreate(Trie:handle);
  * different from the size of the map, since the map can change after the
  * snapshot of its keys was taken.
  *
- * @param handle	Map snapshot.
+ * @param handle    Map snapshot handle
  *
- * @return			Number of keys.
- * @error			Invalid handle.
+ * @return          Number of keys
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown.
  */
 native TrieSnapshotLength(Snapshot:handle);
 
@@ -201,33 +235,37 @@ native TrieSnapshotLength(Snapshot:handle);
  * Returns the buffer size required to store a given key. That is, it returns
  * the length of the key plus one.
  *
- * @param handle	Map snapshot.
- * @param index		Key index (starting from 0).
+ * @param handle    Map snapshot handle
+ * @param index     Key index (starting from 0)
  *
- * @return 			Buffer size required to store the key string.
- * @error			Invalid handle or index out of range.
+ * @return          Buffer size required to store the key string
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown. or index out of range
  */
 native TrieSnapshotKeyBufferSize(Snapshot:handle, index);
 
 /**
  * Retrieves the key string of a given key in a map snapshot.
  *
- * @param handle	Map snapshot.
- * @param index		Key index (starting from 0).
- * @param buffer	String buffer.
- * @param maxlength	Maximum buffer length.
+ * @param handle    Map snapshot handle
+ * @param index     Key index (starting from 0)
+ * @param buffer    String buffer
+ * @param maxlength Maximum buffer length
  *
- * @return			Number of bytes written to the buffer.
- * @error			Invalid handle or index out of range.
+ * @return          Number of bytes written to the buffer
+ * @error           If an invalid handle is provided an error will be
+ *                  thrown. or index out of range
  */
 native TrieSnapshotGetKey(Snapshot:handle, index, buffer[], maxlength);
 
 /**
- * Destroys a Map snapshot
+ * Destroys a map snapshot and frees its memory.
  *
- * @param handle	Map snapshot.
+ * @note The function automatically sets the variable passed to it to 0 to aid
+ *       in preventing accidental usage after destroy.
  *
- * @return			True on success, false if the value was never set.
- * @error			Invalid handle.
+ * @param handle    Map snapshot handle
+ *
+ * @return          1 on success, 0 if an invalid handle was passed in
  */
 native TrieSnapshotDestroy(&Snapshot:handle);

From a1c5c20d7eea972442e56b590ef84cd0386b3c7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Wed, 18 Feb 2015 03:29:26 +0100
Subject: [PATCH 04/10] amxmodx: Consistency updates, typo fixes, missing
 return/error added

---
 plugins/include/amxmodx.inc | 414 ++++++++++++++++++++----------------
 1 file changed, 230 insertions(+), 184 deletions(-)

diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc
index d8178038..fe8d9988 100755
--- a/plugins/include/amxmodx.inc
+++ b/plugins/include/amxmodx.inc
@@ -76,7 +76,7 @@ forward plugin_unpause();
 forward server_changelevel(map[]);
 
 /**
- * Called when all plugins went through plugin_init
+ * Called when all plugins went through plugin_init().
  *
  * @note When this forward is called most plugins should have registered their
  *       cvars and commands already.
@@ -86,8 +86,8 @@ forward server_changelevel(map[]);
 forward plugin_cfg();
 
 /**
- * Called just before server deactivation and subsequent
- * unloading of the plugin.
+ * Called just before server deactivation and subsequent unloading of the
+ * plugin.
  *
  * @note The plugin is required to manually free Handles it has acquired, such
  *       as those from dynamic data structures. Failing to do that will result
@@ -100,8 +100,8 @@ forward plugin_end();
 /**
  * Called when a message is about to be logged.
  *
- * @note Message data and information can be retrieved using the read_log* set
- *       of functions.
+ * @note Message data and information can be retrieved using the read_log set of
+ *       functions.
  *
  * @return      PLUGIN_CONTINUE to let the log message through
  *              PLUGIN_HANDLED or higher to stop the log message
@@ -123,7 +123,7 @@ forward plugin_log();
 forward plugin_precache();
 
 /**
- * Called when a clients info has changed
+ * Called when a clients info has changed.
  *
  * @param id    Client index
  *
@@ -147,7 +147,7 @@ forward client_connect(id);
  * Called when the client gets a valid SteamID.
  *
  * @note This may occur before or after client_putinserver has been called.
- * @note This is called for bots, and the SteamID will be "BOT"
+ * @note This is called for bots, and the SteamID will be "BOT".
  *
  * @param id    Client index
  *
@@ -223,7 +223,7 @@ native precache_model(const name[]);
  * @note Can only be used inside of the plugin_precache() forward.
  * @note The filepath is always relative to the "sound" folder, and the file has
  *       to be a wav file. Precaching a file with this will add it to the engine
- *       sound table, making it available for usage in emit_sound for example.
+ *       sound table, making it available for usage in emit_sound() for example.
  * @note Precaching other filetypes (such as mp3 music), optionally in different
  *       locations, has to be done with precache_generic.
  *
@@ -319,30 +319,33 @@ native get_localinfo(const info[], output[], len);
  * Shows text or a file in MOTD window.
  *
  * @param player    Client index, use 0 to display to all clients
- * @param message   Message to display inside the MOTD window. If this is a
- *                  filename the contents of this file will be displayed.
- * @param header    Text for the MOTD header. If this is empty the servers
- *                  hostname will be displayed instead.
+ * @param message   Message to display inside the MOTD window, if this is a
+ *                  filename the contents of this file will be displayed
+ * @param header    Text for the MOTD header, if empty the servers hostname will
+ *                  be displayed instead
  *
  * @noreturn
  */
-native show_motd(player, const message[], const header[]="");
+native show_motd(player, const message[], const header[] = "");
 
 /**
  * Sends a message to the client.
  *
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
+ *
  * @param index     Client index, use 0 to display to all clients
  * @param type      Message type, see print_* destination constants in amxconst
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native client_print(index, type, const message[], any:...);
 
@@ -365,6 +368,12 @@ native client_print(index, type, const message[], any:...);
  *       client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default")
  * @note Including colors in ML can be done using the same escaping method:
  *       EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default.
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
  *
  * @param index     Client index, use 0 to display to all clients
  * @param sender    Client index used as the sender, defining the team color
@@ -374,30 +383,29 @@ native client_print(index, type, const message[], any:...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native client_print_color(index, sender, const message[], any:...);
 
 /**
  * Sends a message to the client via the engine.
  *
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
+ *
  * @param player    Client index, use 0 to display to all clients
  * @param type      Message type, see print_* destination constants in amxconst
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native engclient_print(player, type, const message[], any:...);
 
@@ -410,7 +418,7 @@ native engclient_print(player, type, const message[], any:...);
  *
  * @return          Number of printed characters
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native console_print(id, const message[], any:...);
 
@@ -463,19 +471,20 @@ native console_cmd(id, const cmd[], any:...);
  *
  * @return          1 on successfully registering event
  *                  0 on failure
- * @error           Invalid event name or invalid callback function
+ * @error           If an invalid event name or callback function is provided,
+ *                  an error will be thrown.
  */
-native register_event(const event[], const function[], const flags[], const cond[]="", ...);
+native register_event(const event[], const function[], const flags[], const cond[] = "", ...);
 
 /**
  * Registers a function to be called on a given log event.
  *
  * @note Examples for log conditions:
- *       "0=World triggered" "1=Game_Commencing"
- *       "1=say"
- *       "3=Terrorists_Win"
- *       "1=entered the game"
- *       "0=Server cvar"
+ *       "0 = World triggered" "1 = Game_Commencing"
+ *       "1 = say"
+ *       "3 = Terrorists_Win"
+ *       "1 = entered the game"
+ *       "0 = Server cvar"
  *
  * @param function  Name of callback function
  * @param argsnum   Number of arguments of the log event
@@ -489,9 +498,10 @@ native register_event(const event[], const function[], const flags[], const cond
  *                  The argument is compared to the specified string accordingly
  *
  * @return          1 on successfully registering event, 0 on failure
- * @error           Invalid callback function
+ * @error           If an invalid callback function is provided, an error will
+ *                  be thrown.
  */
-native register_logevent(const function[], argsnum,  ...);
+native register_logevent(const function[], argsnum, ...);
 
 /**
  * Sets display parameters for hudmessages.
@@ -524,24 +534,26 @@ native register_logevent(const function[], argsnum,  ...);
  *
  * @noreturn
  */
-native set_hudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, effects=0, Float:fxtime=6.0, Float:holdtime=12.0, Float:fadeintime=0.1, Float:fadeouttime=0.2, channel=-1);
+native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y = 0.35, effects = 0, Float:fxtime = 6.0, Float:holdtime = 12.0, Float:fadeintime = 0.1, Float:fadeouttime = 0.2, channel = -1);
 
 /**
  * Displays a message on the client HUD.
  *
  * @note Use set_hudmessage to define how the message should look on screen.
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
  *
  * @param index     Client index, use 0 to display to all clients
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native show_hudmessage(index, const message[], any:...);
 
@@ -568,7 +580,7 @@ native show_hudmessage(index, const message[], any:...);
  *
  * @noreturn
  */
-native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, effects=0, Float:fxtime=6.0, Float:holdtime=12.0, Float:fadeintime=0.1, Float:fadeouttime=0.2);
+native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y = 0.35, effects = 0, Float:fxtime = 6.0, Float:holdtime = 12.0, Float:fadeintime = 0.1, Float:fadeouttime = 0.2);
 
 /**
  * Displays a director message on the client HUD.
@@ -580,18 +592,20 @@ native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, e
  *       sent. There is no way to clear a specific message.
  * @note The message has a maximum length of 128 characters which this function
  *       will automatically enforce.
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
  *
  * @param index     Client index, use 0 to display to all clients
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native show_dhudmessage(index, const message[], any:...);
 
@@ -615,8 +629,13 @@ native show_dhudmessage(index, const message[], any:...);
  * @param menu      Menu body
  * @param time      Menu timeout in seconds, -1 to disable
  * @param title     Name of the menu for internal tracking purposes
+ *
+ * @return          1 on success, 0 if menu could not be displayed (client not
+ *                  connected)
+ * @error           If a single client is specified and the index is not
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
-native show_menu(index, keys, const menu[], time=-1, const title[]="");
+native show_menu(index, keys, const menu[], time = -1, const title[] = "");
 
 /**
  * Retrieves values from a client message.
@@ -627,22 +646,22 @@ native show_menu(index, keys, const menu[], time=-1, const title[]="");
  *       read_data(2, floatvalue);
  *       written = read_data(3, buffer, buffersize);
  *
- *
  * @param value     Argument number to retrieve value from
- * @param ...       If 0 additional parameters are provided, the function
- *                  will return the argument value directly.
- *                  If 1 additional parameter is provided, the function will
- *                  store a float value in that second parameter.
- *                  If two additional parameters are provided, the function
- *                  will copy a string to the buffer provided in the second
- *                  parameter, using the third as the maximum buffer size.
+ * @param ...       Changes the native's behavior depending on how many
+ *                  additional parameters are provided:
+ *                     0 - Return the argument integer value directly
+ *                     1 - Store the argument float value in the variable passed
+ *                         as the second parameter
+ *                     2 - Copy the argument string value to the buffer provided
+ *                         in the second parameter, using the third as the
+ *                         maximum buffer size
  *
- * @return          If zero additional parameters are provided, the function
- *                  will return an integer value.
- *                  If one additional parameter is provided, the function will
- *                  return the float value, converted (truncated) to an integer.
- *                  If two additional parameters are provided, the function
- *                  will return the number of cells written to the buffer.
+ * @return          Changes depending on how many additional parameters are
+ *                  provided:
+ *                     0 - Returns the argument integer value
+ *                     1 - Returns the argument float value, converted
+ *                         (truncated) to an integer
+ *                     2 - Returns the number of cells written to the buffer
  */
 native read_data(value, any:...);
 
@@ -724,7 +743,7 @@ native read_logargv(id, output[], len);
  * @error           If the provided string is not valid client log data, an
  *                  error will be thrown.
  */
-native parse_loguser(const text[], name[], nlen, &userid=-2, authid[]="", alen=0, team[]="", tlen=0);
+native parse_loguser(const text[], name[], nlen, &userid =-2, authid[] = "", alen = 0, team[] = "", tlen = 0);
 
 /**
  * Sends a message to the console of the server.
@@ -768,7 +787,7 @@ native is_user_hltv(index);
  *
  * @note This does not throw an error if the provided index is out of the
  *       1 to MaxClients range. That means you can safely use this native
- *       without manually verifying an index to be a valid client index.
+ *       without manually verifying that the index is a valid client index.
  *
  * @param index     Client index
  *
@@ -842,9 +861,9 @@ native get_amxx_verstring(buffer[], length);
  *       was attacked by a non-client entity.
  *
  * @param index     Client index
- * @param ...       Optionally a second byref parameter will be filled with the
- *                  attacker weapon, and a third byref parameter will be filled
- *                  with the hit place on the body.
+ * @param ...       If provided the attacker weapon will be stored in an
+ *                  optional second parameter, and the body hit place will be
+ *                  stored in an optional third parameter
  *
  * @return          Attacker client index, a non-client entity or 0 if no
  *                  attacker was found
@@ -858,7 +877,7 @@ native get_user_attacker(index, ...);
  * Traces the client's current aim vector to see if it hits something.
  *
  * @note If the trace does not hit a client, id and body will be set to 0.
- * @note If the trace hits nothing within the specified distance 0.0 is returned
+ * @note If the trace hits nothing within the specified distance 0 is returned.
  *
  * @param index     Client index to trace aim from
  * @param id        Variable to store hit client index (if applicable)
@@ -869,7 +888,7 @@ native get_user_attacker(index, ...);
  * @error           If the client index is not within the range of 1 to
  *                  MaxClients an error will be thrown.
  */
-native Float:get_user_aiming(index, &id, &body, dist=9999);
+native Float:get_user_aiming(index, &id, &body, dist = 9999);
 
 /**
  * Returns the client's frags.
@@ -949,7 +968,7 @@ native get_user_index(const name[]);
  *
  * @return                  Number of cells written to the buffer
  */
-native get_user_ip(index, ip[], len, without_port=0);
+native get_user_ip(index, ip[], len, without_port = 0);
 
 /**
  * Returns if the client has the specified weapon in their inventory.
@@ -963,7 +982,7 @@ native get_user_ip(index, ip[], len, without_port=0);
  * @error               If the client index is not within the range of 1 to
  *                      MaxClients an error will be thrown.
  */
-native user_has_weapon(index, weapon, setweapon=-1);
+native user_has_weapon(index, weapon, setweapon = -1);
 
 /**
  * Returns weapon index of the currently carried weapon. Also allows retrieval
@@ -977,7 +996,7 @@ native user_has_weapon(index, weapon, setweapon=-1);
  * @error           If the client index is not within the range of 1 to
  *                  MaxClients an error will be thrown.
  */
-native get_user_weapon(index, &clip=0, &ammo=0);
+native get_user_weapon(index, &clip = 0, &ammo = 0);
 
 /**
  * Retrieves ammo in the clip and backpack of the specified weapon.
@@ -1020,9 +1039,9 @@ native num_to_word(num, output[], len);
  * @param len       Maximum size of buffer
  *
  * @return          Team index on success, -1 if client index is invalid or
- *                  the client is not connected.
+ *                  the client is not connected
  */
-native get_user_team(index, team[]="", len=0);
+native get_user_team(index, team[] = "", len = 0);
 
 /**
  * Returns client's playing time in seconds.
@@ -1034,7 +1053,7 @@ native get_user_team(index, team[]="", len=0);
  * @return          Connection time in seconds, 0 if client index is invalid or
  *                  client is not connected
  */
-native get_user_time(index, flag=0);
+native get_user_time(index, flag = 0);
 
 /**
  * Retrieves the ping and loss of a client.
@@ -1044,7 +1063,7 @@ native get_user_time(index, flag=0);
  * @param loss      Variable to sote loss in
  *
  * @return          1 on success, 0 if client index is invalid or the client
- *                  is not connected.
+ *                  is not connected
  */
 native get_user_ping(index, &ping, &loss);
 
@@ -1064,7 +1083,7 @@ native get_user_ping(index, &ping, &loss);
  * @error           If the client index is not within the range of 1 to
  *                  MaxClients an error will be thrown.
  */
-native get_user_origin(index, origin[3], mode=0);
+native get_user_origin(index, origin[3], mode = 0);
 
 /**
  * Retrieves all weapons in the client inventory, stores them in an array and
@@ -1089,6 +1108,8 @@ native get_user_weapons(index, weapons[32], &num);
  * @param id        Weapon index
  * @param weapon    Buffer to copy name to
  * @param len       Maximum buffer size
+ *
+ * @return          Number of cells written to buffer
  */
 native get_weaponname(id, weapon[], len);
 
@@ -1123,7 +1144,7 @@ native get_user_authid(index, authid[], len);
  * @param index     Client index
  *
  * @return          Client userid, 0 if the userid is not available or the
- *                  client index is invalid.
+ *                  client index is invalid
  */
 native get_user_userid(index);
 
@@ -1139,9 +1160,11 @@ native get_user_userid(index);
  * @param index     Client idex
  * @param power     Power of the slap
  * @param rnddir    If set to zero the player will be slapped along it's aim
- *                  vector. If nonzero the direction will be randomized.
+ *                  vector, otherwise the direction will be randomized
+ *
+ * @return          1 if user is alive and slap succeeded, 0 otherwise
  */
-native user_slap(index, power, rnddir=1);
+native user_slap(index, power, rnddir = 1);
 
 /**
  * Kills a client.
@@ -1150,9 +1173,9 @@ native user_slap(index, power, rnddir=1);
  * @param flag      If nonzero the death will not affect the client's score
  *
  * @return          1 on success, 0 if client index is invalid or the client
- *                  is not connected.
+ *                  is not connected
  */
-native user_kill(index, flag=0);
+native user_kill(index, flag = 0);
 
 /**
  * Logs a message to the current AMXX log file.
@@ -1198,7 +1221,7 @@ native log_to_file(const file[], const message[], any:...);
  *
  * @return          Number of clients on the server
  */
-native get_playersnum(flag=0);
+native get_playersnum(flag = 0);
 
 /**
  * Stores a filtered list of client indexes to an array.
@@ -1221,7 +1244,7 @@ native get_playersnum(flag=0);
  *
  * @noreturn
  */
-native get_players(players[MAX_PLAYERS], &num, const flags[]="", const team[]="");
+native get_players(players[MAX_PLAYERS], &num, const flags[] = "", const team[] = "");
 
 /**
  * Retrieves argument of client command.
@@ -1340,7 +1363,7 @@ native remove_quotes(text[]);
  *
  * @return          Lenght of formatted command string
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native client_cmd(index, const command[], any:...);
 
@@ -1355,16 +1378,16 @@ native client_cmd(index, const command[], any:...);
  * @note Commands emulated using this function will not trigger plugin command
  *       hooks. For an alternative that does, see amxclient_cmd().
  *
- * @param index         Client index, use 0 to execute from all clients.
+ * @param index         Client index, use 0 to execute from all clients
  * @param command       Client command to execute on
  * @param arg1          Optional command arguments
  * @param arg2          Optional command arguments
  *
  * @noreturn
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
-native engclient_cmd(index, const command[], const arg1[]="", const arg2[]="");
+native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
 
 /**
  * Execute a command from the client without actually sending it to the client's
@@ -1377,16 +1400,16 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]="");
  * @note Commands emulated using this function will trigger other plugin's
  *       command hooks. For an alternative that doesn't, see engclient_cmd().
  *
- * @param index         Client index, use 0 to execute from all clients.
+ * @param index         Client index, use 0 to execute from all clients
  * @param command       Client command to execute on
  * @param arg1          Optional command arguments
  * @param arg2          Optional command arguments
  *
  * @noreturn
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
-native amxclient_cmd(index, const command[], const arg1[]="", const arg2[]="");
+native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
 
 /**
  * Queues a command to be executed from the server console.
@@ -1484,20 +1507,20 @@ native get_time(const format[], output[], len);
  * @param time      Unix timestamp, use -1 to use the current time
  *
  * @return          Number of cells written to buffer
- * @error           If the conversion process fails, an error will be thrown
+ * @error           If the conversion process fails, an error will be thrown.
  */
-native format_time(output[], len, const format[], time=-1);
+native format_time(output[], len, const format[], time = -1);
 
 /**
  * Returns the system time as a unix timestamp (number of seconds since unix
- * epoch)
+ * epoch).
  *
  * @param offset    Optional offset value in seconds
  *
  * @return          Unix time stamp
  * @error
  */
-native get_systime(offset=0);
+native get_systime(offset = 0);
 
 /**
  * Converts time string to unix time stamp.
@@ -1512,12 +1535,12 @@ native get_systime(offset=0);
  * @param input     Time string to convert
  * @param format    Formatting information for conversion
  * @param time      If different from -1 the converted time will be added to
- *                  this time stamp.
+ *                  this time stamp
  *
  * @return          Unix time stamp
- * @error           If the conversion process fails, an error will be thrown
+ * @error           If the conversion process fails, an error will be thrown.
  */
-native parse_time(const input[], const format[], time=-1);
+native parse_time(const input[], const format[], time = -1);
 
 /**
  * Calls a function after a specified time has elapsed.
@@ -1536,8 +1559,12 @@ native parse_time(const input[], const format[], time=-1);
  *                              map change
  * @param repeat        If the "a" flag is set the task will be repeated this
  *                      many times
+ *
+ * @noreturn
+ * @error               If an invalid callback function is provided, an error is
+ *                      thrown.
  */
-native set_task(Float:time, const function[], id=0, const any:parameter[]="", len=0, const flags[]="", repeat=0);
+native set_task(Float:time, const function[], id = 0, const any:parameter[] = "", len = 0, const flags[] = "", repeat = 0);
 
 /**
  * Removes all tasks with the specified id.
@@ -1547,7 +1574,7 @@ native set_task(Float:time, const function[], id=0, const any:parameter[]="", le
  *
  * @return          Number of removed tasks
  */
-native remove_task(id=0, outside=0);
+native remove_task(id = 0, outside = 0);
 
 /**
  * Modifies the time interval of all tasks with the specified id.
@@ -1558,7 +1585,7 @@ native remove_task(id=0, outside=0);
  *
  * @return          Number of affected tasks
  */
-native change_task(id=0, Float:newTime=1.0, outside=0);
+native change_task(id = 0, Float:newTime = 1.0, outside = 0);
 
 /**
  * Returns if a task with the specified id exists.
@@ -1568,7 +1595,7 @@ native change_task(id=0, Float:newTime=1.0, outside=0);
  *
  * @return          1 if a task was found, 0 otherwise
  */
-native task_exists(id=0, outside=0);
+native task_exists(id = 0, outside = 0);
 
 /**
  * Sets the specified admin flags to a client.
@@ -1588,7 +1615,7 @@ native task_exists(id=0, outside=0);
  * @error           If the index is not within the range of 0 to MaxClients, an
  *                  error will be thrown.
  */
-native set_user_flags(index, flags=-1, id=0);
+native set_user_flags(index, flags = -1, id = 0);
 
 /**
  * Returns the client's admin flags as a bitflag sum.
@@ -1605,7 +1632,7 @@ native set_user_flags(index, flags=-1, id=0);
  * @error           If the index is not within the range of 0 to MaxClients, an
  *                  error will be thrown.
  */
-native get_user_flags(index, id=0);
+native get_user_flags(index, id = 0);
 
 /**
  * Removes the specified admin flags from a client.
@@ -1624,13 +1651,13 @@ native get_user_flags(index, id=0);
  * @error           If the index is not within the range of 0 to MaxClients, an
  *                  error will be thrown.
  */
-native remove_user_flags(index, flags=-1, id=0);
+native remove_user_flags(index, flags = -1, id = 0);
 
 /**
  * Registers a callback to be called when the client executes a command from the
  * console.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  * @note Opting in to FlagManager enables the admin privileges to be overwritten
  *       by the end user via the cmdaccess.ini config file.
@@ -1649,13 +1676,13 @@ native remove_user_flags(index, flags=-1, id=0);
  * @error               If an invalid callback function is specified, an error
  *                      will be thrown.
  */
-native register_clcmd(const client_cmd[], const function[], flags=-1, const info[]="", FlagManager=-1);
+native register_clcmd(const client_cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1);
 
 /**
  * Registers a callback to be called when the client or server executes a
  * command from the console.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  * @note Opting in to FlagManager enables the admin privileges to be overwritten
  *       by the end user via the cmdaccess.ini config file.
@@ -1674,13 +1701,13 @@ native register_clcmd(const client_cmd[], const function[], flags=-1, const info
  * @error               If an invalid callback function is specified, an error
  *                      will be thrown.
  */
-native register_concmd(const cmd[], const function[], flags=-1, const info[]="", FlagManager=-1);
+native register_concmd(const cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1);
 
 /**
  * Registers a callback to be called when the server executes a command from the
  * console.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param client_cmd    Command to register
@@ -1692,12 +1719,12 @@ native register_concmd(const cmd[], const function[], flags=-1, const info[]="",
  * @error               If an invalid callback function is specified, an error
  *                      will be thrown.
  */
-native register_srvcmd(const server_cmd[], const function[], flags=-1, const info[]="");
+native register_srvcmd(const server_cmd[], const function[], flags = -1, const info[] = "");
 
 /**
  * Retrieves information about a client command.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1707,7 +1734,7 @@ native register_srvcmd(const server_cmd[], const function[], flags=-1, const inf
  * @param info      Buffer to copy command description to
  * @param len2      Maximum description buffer size
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  *
  * @return          1 on succes, 0 if command was not found
  */
@@ -1716,11 +1743,11 @@ native get_clcmd(index, command[], len1, &flags, info[], len2, flag);
 /**
  * Returns number of registered client commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  *
  * @return          Number of registered client commants
  */
@@ -1729,7 +1756,7 @@ native get_clcmdsnum(flag);
 /**
  * Retrieves information about a server command.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1739,7 +1766,7 @@ native get_clcmdsnum(flag);
  * @param info      Buffer to copy command description to
  * @param len2      Maximum description buffer size
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  *
  * @return          1 on succes, 0 if command was not found
  */
@@ -1748,11 +1775,11 @@ native get_srvcmd(index, server_cmd[], len1, &flags, info[], len2, flag);
 /**
  * Returns number of registered server commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  *
  * @return          Number of registered server commants
  */
@@ -1761,7 +1788,7 @@ native get_srvcmdsnum(flag);
 /**
  * Retrieves information about a console command.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1771,19 +1798,19 @@ native get_srvcmdsnum(flag);
  * @param info      Buffer to copy command description to
  * @param len2      Maximum description buffer size
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  * @param id        If set to 0 only server commands will be considered,
  *                  positive will only consider client commands, otherwise
- *                  all console commands will be considered.
+ *                  all console commands will be considered
  *
  * @return          1 on succes, 0 if command was not found
  */
-native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id=-1);
+native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id = -1);
 
 /**
- * Returns the parent plugin id of a console command
+ * Returns the parent plugin id of a console command.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param cid           Command index
@@ -1792,24 +1819,26 @@ native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id=-1);
  * @param id_type       If set to 0 only server commands will be considered,
  *                      positive will only consider client commands, otherwise
  *                      all console commands will be considered.
+ *
+ * @return              Plugin id
  */
 native get_concmd_plid(cid, flag_mask, id_type);
 
 /**
  * Returns number of registered console commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
- *                  the specified privilege flags.
+ *                  the specified privilege flags
  * @param id        If set to 0 only server commands will be considered,
  *                  positive will only consider client commands, otherwise
- *                  all console commands will be considered.
+ *                  all console commands will be considered
  *
  * @return          Number of registered console commants
  */
-native get_concmdsnum(flag, id=-1);
+native get_concmdsnum(flag, id = -1);
 
 /**
  * Returns unique menu id of a menu.
@@ -1819,7 +1848,7 @@ native get_concmdsnum(flag, id=-1);
  *
  * @return          Menu id
  */
-native register_menuid(const menu[], outside=0);
+native register_menuid(const menu[], outside = 0);
 
 /**
  * Registers a callback function to a menu id and keys.
@@ -1877,6 +1906,8 @@ native server_exec();
  * @param att       Sound attenuation
  * @param flags     Emit flags
  * @param pitch     Sound pitch
+ *
+ * @noreturn
  */
 native emit_sound(index, channel, const sample[], Float:vol, Float:att, flags, pitch);
 
@@ -1901,7 +1932,7 @@ native Float:random_float(Float:a, Float:b);
 native random_num(a, b);
 
 /**
- * Returns unique id of a client message
+ * Returns unique id of a client message.
  *
  * @note Example usage: get_user_msgid("TextMsg")
  * @note The message id is unique as long as the server is running, but might
@@ -1989,7 +2020,7 @@ native Float:get_xvar_float(id);
  * @noreturn
  * @error           If an invalid xvar id is specified an error will be thrown.
  */
-native set_xvar_num(id, value=0);
+native set_xvar_num(id, value = 0);
 
 /**
  * Sets the float value of a public variable.
@@ -2005,7 +2036,7 @@ native set_xvar_num(id, value=0);
  * @noreturn
  * @error           If an invalid xvar id is specified an error will be thrown.
  */
-native set_xvar_float(id, Float:value=0.0);
+native set_xvar_float(id, Float:value = 0.0);
 
 /**
  * Returns if a module is loaded.
@@ -2058,7 +2089,7 @@ native get_modulesnum();
  *
  * @return              Plugin id of the matching plugin, -1 otherwise
  */
-native is_plugin_loaded(const name[], bool:usefilename=false);
+native is_plugin_loaded(const name[], bool:usefilename = false);
 
 /**
  * Retrieves info about a plugin by plugin index.
@@ -2079,7 +2110,7 @@ native is_plugin_loaded(const name[], bool:usefilename=false);
  * @return          Plugin index on success, -1 if there is no plugin with given
  *                  index
  */
-native get_plugin(index, filename[]="", len1=0, name[]="", len2=0, version[]="", len3=0, author[]="", len4=0, status[]="", len5=0, ...);
+native get_plugin(index, filename[] = "", len1 = 0, name[] = "", len2 = 0, version[] = "", len3 = 0, author[] = "", len4 = 0, status[] = "", len5 = 0, ...);
 
 /**
  * Returns the number of loaded AMXX plugins.
@@ -2106,7 +2137,7 @@ native get_pluginsnum();
  * @error           If it is attempted to use the deprecated functionality,
  *                  an error is thrown.
  */
-native pause(const flag[], const param1[]="", const param2[]="");
+native pause(const flag[], const param1[] = "", const param2[] = "");
 
 /**
  * Unpauses a plugin so it will resume execution if it was previously paused.
@@ -2127,14 +2158,14 @@ native pause(const flag[], const param1[]="", const param2[]="");
  * @error           If it is attempted to use the deprecated functionality,
  *                  an error is thrown.
  */
-native unpause(const flag[], const param1[]="", const param2[]="");
+native unpause(const flag[], const param1[] = "", const param2[] = "");
 
 /**
  * Initiates a function call to this or another plugin by function name.
  *
  * @note This only sets up the function call and covers the pre-requisites.
  *       Push parameters using the callfunc_push_* set of functions. The call
- *       will be executed only upon using callfunc_end()
+ *       will be executed only upon using callfunc_end().
  *
  * @param func      Function name
  * @param plugin    Plugin filename. If empty the calling plugin is targeted.
@@ -2147,15 +2178,15 @@ native unpause(const flag[], const param1[]="", const param2[]="");
  * @error           If called while another callfunc has not yet been finished,
  *                  an error is thrown.
  */
-native callfunc_begin(const func[], const plugin[]="");
+native callfunc_begin(const func[], const plugin[] = "");
 
 /**
  * Initiates a function call to this or another plugin by function id.
  *
  * @note This only sets up the function call and covers the pre-requisites.
  *       Push parameters using the callfunc_push_* set of functions. The call
- *       will be executed only upon using callfunc_end()
- * @note The function id can be retrieved by get_func_id()
+ *       will be executed only upon using callfunc_end().
+ * @note The function id can be retrieved by get_func_id().
  *
  * @param func      Function id
  * @param plugin    Plugin filename. If empty the calling plugin is targeted.
@@ -2167,10 +2198,10 @@ native callfunc_begin(const func[], const plugin[]="");
  * @error           If called while another callfunc has not yet been finished,
  *                  or the specified function is invalid, an error is thrown.
  */
-native callfunc_begin_i(func, plugin=-1);
+native callfunc_begin_i(func, plugin = -1);
 
 /**
- * Retrieves a functions id for use with callfunc_begin_i()
+ * Retrieves a functions id for use with callfunc_begin_i().
  *
  * @param funcName  Function name
  * @param pluginId  Plugin id. If -1 the calling plugin is targeted. The plugin
@@ -2179,7 +2210,7 @@ native callfunc_begin_i(func, plugin=-1);
  * @return          >0 Function id on success
  *                  -1 if plugin or function was not found
  */
-native get_func_id(const funcName[], pluginId=-1);
+native get_func_id(const funcName[], pluginId = -1);
 
 /**
  * Pushes an int value onto the current call.
@@ -2239,13 +2270,13 @@ native callfunc_push_floatrf(&Float:value);
  *
  * @param VALUE     String to push
  * @param copyback  If true any changes made in the called function will be
- *                  copied back to the calling plugin.
+ *                  copied back to the calling plugin
  *
  * @noreturn
  * @error           If called without initiating a callfunc, or the maximum
  *                  amount of parameters is reached, an error is thrown.
  */
-native callfunc_push_str(const VALUE[], bool:copyback=true);
+native callfunc_push_str(const VALUE[], bool:copyback = true);
 
 /**
  * Pushes an array onto the current call.
@@ -2256,13 +2287,13 @@ native callfunc_push_str(const VALUE[], bool:copyback=true);
  * @param VALUE         Array to push
  * @param array_size    Size of the array
  * @param copyback      If true any changes made in the called function will be
- *                      copied back to the calling plugin.
+ *                      copied back to the calling plugin
  *
  * @noreturn
  * @error           If called without initiating a callfunc, or the maximum
  *                  amount of parameters is reached, an error is thrown.
  */
-native callfunc_push_array(const VALUE[], array_size, bool:copyback=true);
+native callfunc_push_array(const VALUE[], array_size, bool:copyback = true);
 
 /**
  * Completes the call to a function.
@@ -2329,11 +2360,13 @@ native md5_file(const file[], md5buffer[34]);
  * @param hdr       If nonzero the function will return the pcode rather than
  *                  state flags
  * @param plid      Plugin id, -1 to target calling plugin
+ *
+ * @return          Plugin flags
  */
-native plugin_flags(hdr=0, plid=-1);
+native plugin_flags(hdr = 0, plid = -1);
 
 /**
- * Allows plugins to declare module dependencies using require_module()
+ * Allows plugins to declare module dependencies using require_module().
  *
  * @deprecated Module dependency has been automatically handled by the compiler
  *             since AMXX 1.50, released in 2005. This forward is no longer
@@ -2345,7 +2378,7 @@ native plugin_flags(hdr=0, plid=-1);
 forward plugin_modules();
 
 /**
- * Adds a module dependency
+ * Adds a module dependency.
  *
  * @deprecated Module dependency has been automatically handled by the compiler
  *             since AMXX 1.50, released in 2005. This native has no effect.
@@ -2358,7 +2391,7 @@ native require_module(const module[]);
 /**
  * Returns if the server is 64 bit.
  *
- * @deprecated As a result of valve dropping support for 64bit binaries AMXX is
+ * @deprecated As a result of Valve dropping support for 64bit binaries AMXX is
  *             also not shipping 64bit builds anymore. This native is basically
  *             guaranteed to return 0.
  *
@@ -2376,7 +2409,7 @@ native is_amd64_server();
  *
  * @return              Plugin id, -1 (INVALID_PLUGIN_ID) on failure
  */
-native find_plugin_byfile(const filename[], ignoreCase=1);
+native find_plugin_byfile(const filename[], ignoreCase = 1);
 
 /**
  * Called before plugin_init(), allows the plugin to register natives.
@@ -2392,8 +2425,8 @@ forward plugin_natives();
  *
  * public native_handler(plugin_id, argc)
  *
- * plugin_id    - plugin calling the native
- * argc         - number of parameters
+ *   plugin_id    - plugin calling the native
+ *   argc         - number of parameters
  *
  * @note Style 1 natives are deprecated. Plugins should not use them, they might
  *       break.
@@ -2410,7 +2443,7 @@ forward plugin_natives();
  * @noreturn
  * @error           If an invalid callback is specified, an error is thrown.
  */
-native register_native(const name[], const handler[], style=0);
+native register_native(const name[], const handler[], style = 0);
 
 /**
  * Registers the plugin as a library.
@@ -2620,16 +2653,18 @@ native set_array_f(param, const Float:source[], size);
  *
  * public error_filter(error_code, bool:debugging, message[])
  *
- *  error_code      - AMX_ERR_* code.
- *  debugging       - True if the plugin is in debug mode, false otherwise
- *  message[]       - Message sent along with the error
+ *   error_code      - AMX_ERR_* code.
+ *   debugging       - True if the plugin is in debug mode, false otherwise
+ *   message[]       - Message sent along with the error
  *
  * @note The handler should return PLUGIN_CONTINUE to let the error through the
  *       filter, or PLUGIN_HANDLED to block the error from displaying.
  *
- * @param handler       Callback function
+ * @param handler       Function name to call
  *
- * @error               If an invalid callback is specified, an error is thrown.
+ * @noreturn
+ * @error               If an invalid callback function is provided, an error
+ *                      is thrown.
  */
 native set_error_filter(const handler[]);
 
@@ -2691,15 +2726,22 @@ native dbg_fmt_error(buffer[], maxLength);
  *
  * public native_filter(const native[], index, trap)
  *
- *  native      - Native name
- *  index       - Native index
- *  trap        - 0 if native couldn't be found, 1 if native use was attempted
+ *   native      - Native name
+ *   index       - Native index
+ *   trap        - 0 if native couldn't be found, 1 if native use was attempted
  *
  * @note The handler should return PLUGIN_CONTINUE to let the error through the
  *       filter (which will throw a run-time error), or return PLUGIN_HANDLED
  *       to continue operation.
  * @note Returning PLUGIN_CONTINUE if trap is 0 will result in the plugin
  *       failing to load!
+ *
+ * @param handler   Function name to call
+ *
+ * @return          1 if handler is set successfully, 0 otherwise (called
+ *                  outside of plugin_native() forward)
+ * @error           If an invalid callback function is provided an error is
+ *                  thrown.
  */
 native set_native_filter(const handler[]);
 
@@ -2718,8 +2760,8 @@ native set_native_filter(const handler[]);
  *
  * public module_filter(const library[], LibType:type)
  *
- *  library     - Shortname of library or class that is required
- *  libtrype    - Type of requirement being checked (library/module or class)
+ *   library     - Shortname of library or class that is required
+ *   libtrype    - Type of requirement being checked (library/module or class)
  *
  * @note The handler should return PLUGIN_CONTINUE to let the error through the
  *       filter (which will result in the plugin failing to load), or
@@ -2750,7 +2792,7 @@ native set_module_filter(const handler[]);
  * @error           The function is guaranteed to throw an error, using the
  *                  specified custom log message.
  */
-native abort(error, const fmt[]="", any:...);
+native abort(error, const fmt[] = "", any:...);
 
 /**
  * Returns if a specific module is loaded.
@@ -2812,7 +2854,7 @@ native next_hudchannel(player);
  *
  * @return      HUD sync object handle
  */
-native CreateHudSyncObj(num=0, ...);
+native CreateHudSyncObj(num = 0, ...);
 
 /**
  * Displays a synchronized HUD message.
@@ -2823,6 +2865,12 @@ native CreateHudSyncObj(num=0, ...);
  *       already.
  * @note This uses the display parameters set with set_hudmessage(), ignoring
  *       the selected channel in favor of its own synchronization.
+ * @note This functions return value behaves differently depending on what is
+ *       used as the client index: If 0 is specified, then the function will
+ *       return 0 if nothing has been sent (no client connected). If either a
+ *       single client is specified or there is at least one client connected,
+ *       the number of printed characters will refer to the message that is sent
+ *       last, to the client with the highest index.
  *
  * @param target    Client index, use 0 to display to all clients
  * @param syncObj   HUD sync object handle
@@ -2830,12 +2878,8 @@ native CreateHudSyncObj(num=0, ...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- *                  If 0 is specified as the index then 0 will be returned if
- *                  nothing has been sent. The number of printed characters will
- *                  otherwise refer to the message that is sent last, to the
- *                  client with the highest index.
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native ShowSyncHudMsg(target, syncObj, const fmt[], any:...);
 
@@ -2853,7 +2897,7 @@ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...);
  *
  * @noreturn
  * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown
+ *                  within the range of 1 to MaxClients an error will be thrown.
  */
 native ClearSyncHud(target, syncObj);
 
@@ -2906,6 +2950,7 @@ native get_var_addr(any:...);
  *
  * @param addr      Variable address
  *
+ * @return          Value at address
  * @error           If the plugin attempts to access an address outside of the
  *                  stack or heap limits of the plugin, an error will be thrown.
  */
@@ -2919,6 +2964,7 @@ native get_addr_val(addr);
  * @param addr      Variable address
  * @param val       Value to set
  *
+ * @noreturn
  * @error           If the plugin attempts to access an address outside of the
  *                  stack or heap limits of the plugin, an error will be thrown.
  */
@@ -2967,7 +3013,7 @@ native CreateOneForward(plugin_id, const name[], ...);
  *
  * @return              Special handle for use in ExecuteForward()
  */
-native PrepareArray(const array[], size, copyback=0);
+native PrepareArray(const array[], size, copyback = 0);
 
 /**
  * Executes a forward.
@@ -3019,9 +3065,9 @@ native arrayset(array[], value, size);
 native get_weaponid(const name[]);
 
 /**
- * Adds an admin to the dynamic admin storage for lookup at a later time
+ * Adds an admin to the dynamic admin storage for lookup at a later time.
  *
- * @note For a list of possible access flags see the ADMIN_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  * @note For a list of possible auth flags see the FLAG_* constants in
  *       amxconst.inc
@@ -3036,7 +3082,7 @@ native get_weaponid(const name[]);
 native admins_push(const AuthData[], const Password[], Access, Flags);
 
 /**
- * Returns the number of admins in the dynamic admin storage
+ * Returns the number of admins in the dynamic admin storage.
  *
  * @return  Number of admins
  */
@@ -3054,14 +3100,14 @@ native admins_num();
  * @param BufferSize    Maximum buffer size
  *
  * @return              Property value if AdminProp_Access or AdminProp_Flags
- *                      is requested. 0 otherwise.
+ *                      is requested, 0 otherwise
  * @error               If an invalid storage index is specified, an error will
  *                      be thrown.
  */
-native admins_lookup(num, AdminProp:Property, Buffer[]="", BufferSize=0);
+native admins_lookup(num, AdminProp:Property, Buffer[] = "", BufferSize = 0);
 
 /**
- * Clears the list of dynamically stored admins
+ * Clears the list of dynamically stored admins.
  *
  * @noreturn
  */

From 50fea6be756fcb471b9b863be89db79791daf3aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Wed, 18 Feb 2015 16:24:04 +0100
Subject: [PATCH 05/10] cstrike/csx/csstats: Added documentation, consistency
 updates, typo fixes

---
 plugins/include/csstats.inc |  293 ++++++--
 plugins/include/cstrike.inc | 1349 ++++++++++++++++++++++++++---------
 plugins/include/csx.inc     |  278 ++++++--
 3 files changed, 1500 insertions(+), 420 deletions(-)

diff --git a/plugins/include/csstats.inc b/plugins/include/csstats.inc
index eb8dd300..9bb7c099 100755
--- a/plugins/include/csstats.inc
+++ b/plugins/include/csstats.inc
@@ -12,58 +12,263 @@
 #endif
 #define _csstats_included
 
-/* Gets stats from given weapon index. If wpnindex is 0
-* then the stats are from all weapons. If weapon has not been used function
-* returns 0 in other case 1. Fields in stats are:
-* 0 - kills
-* 1 - deaths
-* 2 - headshots
-* 3 - teamkilling
-* 4 - shots
-* 5 - hits
-* 6 - damage
+/**
+ * Retrieves the client's current weapon statistics.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Weapon id, or 0 to retrieve total statistics across all
+ *                  weapons
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available for the weapon
+ *                  id
+ * @error           If an invalid client index or weapon id is provided, an
+ *                  error will be thrown.
+ */
+native get_user_wstats(index, wpnindex, stats[8], bodyhits[8]);
 
-* For body hits fields see amxconst.inc. */
-native get_user_wstats(index,wpnindex,stats[8],bodyhits[8]);
+/**
+ * Retrieves the client's weapon statistics from the current round.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Weapon id, or 0 to retrieve total statistics across all
+ *                  weapons
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available for the
+ *                  weapon id
+ * @error           If an invalid client index or weapon id is provided, an
+ *                  error will be thrown.
+ */
+native get_user_wrstats(index, wpnindex, stats[8], bodyhits[8]);
 
-/* Gets round stats from given weapon index.*/
-native get_user_wrstats(index,wpnindex,stats[8],bodyhits[8]);
+/**
+ * Retrieves the client's weapon statistics from the permanent storage on the
+ * server.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note Player rank is determined by the difference of kills to deaths.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *          7 - Rank
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          Players rank > 0 on success, or 0 if player is not ranked
+ *                  and no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
+native get_user_stats(index, stats[8], bodyhits[8]);
 
-/* Gets overall stats which are stored in file on server
-* and updated on every respawn or user disconnect.
-* Function returns the position in stats by diff. kills to deaths. */
-native get_user_stats(index,stats[8],bodyhits[8]);
+/**
+ * Retrieves the client's statistics from the current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
+native get_user_rstats(index, stats[8], bodyhits[8]);
 
-/* Gets round stats of player. */
-native get_user_rstats(index,stats[8],bodyhits[8]);
+/**
+ * Retrieves the client's statistics inflicted upon another client from the
+ * current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param victim    Victim client index, or 0 to retrieve the statistics against
+ *                  all victims
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ * @param wpnname   Optional buffer to copy last used weapon name to
+ * @param len       Maximum buffer size
+ *
+ * @return          1 on success, 0 if no statistics are available against the
+ *                  specified victim
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
+native get_user_vstats(index, victim, stats[8], bodyhits[8], wpnname[] = "", len = 0);
 
-/* Gets stats with which user have killed/hurt his victim. If victim is 0
-* then stats are from all victims. If victim has not been hurt, function
-* returns 0 in other case 1. User stats are reset on his respawn. */
-native get_user_vstats(index,victim,stats[8],bodyhits[8],wpnname[]="",len=0);
+/**
+ * Retrieves the client's statistics received from another client from the
+ * current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Attacker client index, or 0 to retrieve the statistics from
+ *                  all attackers
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ * @param wpnname   Optional buffer to copy last used weapon name to
+ * @param len       Maximum buffer size
+ *
+ * @return          1 on success, 0 if no statistics are available against the
+ *                  specified attacker
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
+native get_user_astats(index, wpnindex, stats[8], bodyhits[8], wpnname[] = "", len = 0);
 
-/* Gets stats with which user have been killed/hurt. If killer is 0
-* then stats are from all attacks. If killer has not hurt user, function
-* returns 0 in other case 1. User stats are reset on his respawn. */
-native get_user_astats(index,wpnindex,stats[8],bodyhits[8],wpnname[]="",len=0);
-
-/* Resets life, weapon, victims and attackers user stats. */
+/**
+ * Resets the current round weapon, attacker and victim statistics.
+ *
+ * @param index     Client index
+ *
+ * @noreturn
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native reset_user_wstats(index);
 
-/* Gets overall stats which stored in stats.dat file in amx folder
-* and updated on every mapchange or user disconnect.
-* Function returns next index of stats entry or 0 if no more exists. */
-native get_stats(index,stats[8],bodyhits[8],name[],len,authid[] = "",authidlen = 0);
+/**
+ * Retrieves statistics from the permanent storage on the server via iterative,
+ * incremental access.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note Player rank is determined by the difference of kills to deaths.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *          7 - Rank
+ *
+ * @param index         Rank index
+ * @param stats         Buffer to copy statistics to
+ * @param bodyhits      Buffer to copy body hits to
+ * @param name          Buffer to copy client name to
+ * @param len           Maximum name buffer size
+ * @param authid        Buffer to copy client auth id to
+ * @param authidlen     Maximum authid buffer size
+ *
+ * @return              Next rank index (> 0 and > index), or 0 if no more
+ *                      statistics exist
+ */
+native get_stats(index, stats[8], bodyhits[8], name[], len, authid[] = "", authidlen = 0);
 
-/* Returns number of all entries in stats. */
+/**
+ * Returns the number of all entries in the permanent statistics storage.
+ *
+ * @return  Number of entries in statistics storage
+ */
 native get_statsnum();
 
-/*
-* new stats:
-* 0 - total defusions
-* 1 - bomb defused
-* 2 - bomb plants
-* 3 - bomb explosions
-*/
-native get_user_stats2(index,stats[4]);
-native get_stats2(index,stats[4],authid[] = "",authidlen = 0);
+/**
+ * Retrieves the client's objective statistics from the permanent storage.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note The fields in the statistics are:
+ *          0 - total defusions
+ *          1 - bomb defused
+ *          2 - bomb plants
+ *          3 - bomb explosions
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ *
+ * @return          Players rank > 0 on success, or 0 if player is not ranked
+ *                  and no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
+native get_user_stats2(index, stats[4]);
+
+/**
+ * Retrieves objective statistics from the permanent storage on the server via
+ * iterative, incremental access.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note The fields in the statistics are:
+ *          0 - total defusions
+ *          1 - bomb defused
+ *          2 - bomb plants
+ *          3 - bomb explosions
+ *
+ * @param index         Client index
+ * @param stats         Buffer to copy statistics to
+ * @param authid        Buffer to copy client auth id to
+ * @param authidlen     Maximum authid buffer size
+ *
+ * @return              Next rank index (> 0 and > index), or 0 if no more
+ *                      statistics exist
+ */
+native get_stats2(index, stats[4], authid[] = "", authidlen = 0);
diff --git a/plugins/include/cstrike.inc b/plugins/include/cstrike.inc
index 6bd2846d..2ee0752d 100755
--- a/plugins/include/cstrike.inc
+++ b/plugins/include/cstrike.inc
@@ -12,7 +12,7 @@
 //
 
 #if defined _cstrike_included
-  #endinput
+ #endinput
 #endif
 #define _cstrike_included
 
@@ -25,329 +25,1060 @@
  #pragma library cstrike
 #endif
 
-/* Returns player deaths.
+/**
+ * @section Team and team model constants, used by cs_[get|set]_user_team().
  */
-native cs_get_user_deaths(index);
 
-/* Sets player deaths.
+/**
+ * Internal Counter-Strike model id constants.
+ *
+ * @note Model ids starting with CZ_ are only valid in Condition Zero.
  */
-native cs_set_user_deaths(index, newdeaths);
-
-/* Returns index of entity (does not have to be a player) which hostage is following. 0 is hostage doesn't follow anything.
- * Note: this native does not work on Condition Zero, which has a different hostage AI than CS.
- */
-native cs_get_hostage_foll(index);
-
-/* Set hostage to follow entity specified in followedindex. Does not have to be a player. If followedindex is 0 the hostage will stop following.
- * Note: this native does not work on Condition Zero, which has a different hostage AI than CS.
- */
-native cs_set_hostage_foll(index, followedindex = 0);
-
-/* Get unique hostage id.
- */
-native cs_get_hostage_id(index);
-
-/* Get amount of ammo in backpack on a user for a specific weapon.
- * Look in amxconst.inc for weapon types: CSW_*.
- * Weapons on the same line uses the same ammo type:
- * awm
- * scout, ak, g3
- * para
- * famas, m4a1, aug, sg550, galil, sg552
- * m3, xm
- * usp, ump, mac
- * fiveseven, p90
- * deagle
- * p228
- * glock, mp5, tmp, elites
- * flash
- * he
- * smoke
- */
-native cs_get_user_bpammo(index, weapon);
-
-/* Restock/remove ammo in a user's backpack.
- */
-native cs_set_user_bpammo(index, weapon, amount);
-
-/* Returns 1 if user has a defuse kit.
- */
-native cs_get_user_defuse(index);
-
-/* If defusekit is 1, the user will have a defuse kit.
- * You can specify a different colour for the defuse kit icon showing on hud. Default is the normal green.
- * You can specify an icon. Default is "defuser". Set flash to 1 if you want the icon to flash red.
- */
-native cs_set_user_defuse(index, defusekit = 1, r = 0, g = 160, b = 0, icon[] = "defuser", flash = 0);
-
-/* Is user in buyzone? Returns 1 when true, 0 when false.
- */
-native cs_get_user_buyzone(index);
-
-/* Returns 1 when user has a primary weapon OR a shield in inventory, else 0.
- */
-native cs_get_user_hasprim(index);
-
-/* Get user model.
- */
-native cs_get_user_model(index, model[], len);
-
-/* Set user model.
- */
-native cs_set_user_model(index, const model[]);
-
-/* Use to reset model to standard selected model.
- */
-native cs_reset_user_model(index);
-
-/* Returns users money.
- */
-native cs_get_user_money(index);
-
-/* Gives money to user. If flash is 1, the difference between new and old amount will flash red or green.
- */
-native cs_set_user_money(index, money, flash = 1);
-
-/* Does user have night vision goggles?
- */
-native cs_get_user_nvg(index);
-
-/* Set nvgoggles to 1 to give night vision goggles to index. Set it to 0 to remove them.
- */
-native cs_set_user_nvg(index, nvgoggles = 1);
-
-/* Returns 1 if user has the "skill" to plant bomb, else 0. Normally this would only be true for a terrorist carrying a bomb.
- */
-native cs_get_user_plant(index);
-
-/* If plant is 1, a user will be set to be able to plant bomb within the usual bomb target areas if having one.
- * You should use this if you give a player a weapon_c4, or he won't be able to plant it
- * without dropping it and picking it up again (only possible for terrorists).
- * If showbombicon is 1, the green C4 icon will be shown on user hud (if plant "skill" was enabled).
- */
-native cs_set_user_plant(index, plant = 1, showbombicon = 1);
-
-/* Set user team without killing player.
- * If model is anything other than CS_DONTCHANGE, that will be set as player's model.
- */
-enum CsInternalModel {
-	CS_DONTCHANGE = 0,
-	CS_CT_URBAN = 1,
-	CS_T_TERROR = 2,
-	CS_T_LEET = 3,
-	CS_T_ARCTIC = 4,
-	CS_CT_GSG9 = 5,
-	CS_CT_GIGN = 6,
-	CS_CT_SAS = 7,
-	CS_T_GUERILLA = 8,
-	CS_CT_VIP = 9,
-	CZ_T_MILITIA = 10,
-	CZ_CT_SPETSNAZ = 11
+enum CsInternalModel
+{
+    CS_DONTCHANGE = 0,
+    CS_CT_URBAN = 1,
+    CS_T_TERROR = 2,
+    CS_T_LEET = 3,
+    CS_T_ARCTIC = 4,
+    CS_CT_GSG9 = 5,
+    CS_CT_GIGN = 6,
+    CS_CT_SAS = 7,
+    CS_T_GUERILLA = 8,
+    CS_CT_VIP = 9,
+    CZ_T_MILITIA = 10,
+    CZ_CT_SPETSNAZ = 11,
 };
-native cs_set_user_team(index, {CsTeams,_}:team, {CsInternalModel,_}:model = CS_DONTCHANGE);
 
-/* Get team directly from player's entity.
- * 1 = terrorist
- * 2 = counter-terrorist
- * 3 = spectator
+/**
+ * Counter-Strike team id constants.
  */
-enum CsTeams {
-	CS_TEAM_UNASSIGNED = 0,
-	CS_TEAM_T = 1,
-	CS_TEAM_CT = 2,
-	CS_TEAM_SPECTATOR = 3
+enum CsTeams
+{
+    CS_TEAM_UNASSIGNED = 0,
+    CS_TEAM_T = 1,
+    CS_TEAM_CT = 2,
+    CS_TEAM_SPECTATOR = 3,
 };
-native CsTeams:cs_get_user_team(index, &{CsInternalModel,_}:model = CS_DONTCHANGE);
 
-/* Is user vip? Returns 1 if true, 0 if false.
+/**
+ * @endsection
  */
-native cs_get_user_vip(index);
 
-/* If vip = 1, user is set to vip.
- * If model = 1, then user's model will be changed to VIP model or random CT model if vip = 0.
- * If scoreboard = 1, then scoreboard will be updated to show that user is VIP.
- * This shouldn't be used for players on teams other than CT.
- * NOTE:	this is mostly useful for unsetting vips, so they can change teams and/or buy items properly.
- * It does not alter game play; the one being VIP at start of round will retain internal status as VIP; terrorists
- * can terminate him and accomplish their objective, etc.
+/**
+ * Counter-Strike armor types for use with cs_[get|set]_user_armor().
  */
- native cs_set_user_vip(index, vip = 1, model = 1, scoreboard = 1);
-
-/* Returns 1 of specified user has tk:ed (team killed).
- */
-native cs_get_user_tked(index);
-
-/* Returns 1 of specified user has TKed (team killed).
- * tk = 1: player has TKed
- * tk = 0: player hasn't TKed
- * Set subtract to how many frags to subtract. Set subtract to negative value to add frags.
- */
-native cs_set_user_tked(index, tk = 1, subtract = 1);
-
-/* Returns different values depending on if user is driving a vehicle - and if so at what speed.
- * 0: no driving
- * 1: driving, but standing still
- * 2-4: driving, different positive speeds
- * 5: driving, negative speed (backing)
- * Note: these values were tested quickly, they may differ.
- */
-native cs_get_user_driving(index);
-
-/* Returns 1 if user has a shield, else 0.
- */
-native cs_get_user_shield(index);
-
-/* Returns 1 if user is using a stationary gun, else 0.
- */
-native cs_get_user_stationary(index);
-
-/* Returns armor value and sets by reference the armor type in second parameter.
- */
-enum CsArmorType {
-	CS_ARMOR_NONE = 0, // no armor
-	CS_ARMOR_KEVLAR = 1, // armor
-	CS_ARMOR_VESTHELM = 2 // armor and helmet
+enum CsArmorType
+{
+    CS_ARMOR_NONE = 0,      // no armor
+    CS_ARMOR_KEVLAR = 1,    // body vest only
+    CS_ARMOR_VESTHELM = 2,  // vest and helmet
 };
-native cs_get_user_armor(index, &CsArmorType:armortype);
 
-/* Use this instead of fun's set_user_armor.
- * Appropriate message to update client's HUD will be sent if armortype is kevlar or vesthelm.
+/**
+ * Map zone flags returned by cs_get_user_mapzones().
  */
-native cs_set_user_armor(index, armorvalue, CsArmorType:armortype);
+#define CS_MAPZONE_BUY              (1<<0) // Buyzone
+#define CS_MAPZONE_BOMBTARGET       (1<<1) // Bomb target zone
+#define CS_MAPZONE_HOSTAGE_RESCUE   (1<<2) // Hostage rescue zone
+#define CS_MAPZONE_ESCAPE           (1<<3) // Terrorist escape zone
+#define CS_MAPZONE_VIP_SAFETY       (1<<4) // VIP escape zone
 
-/* Returns 1 if specified weapon is in burst mode.
- */
-native cs_get_weapon_burst(index);
-
-/* If burstmode = 1, weapon will be changed to burst mode, 0 and non-burst mode (semiautomatic/automatic) will be activated.
- * Only GLOCK and FAMAS can enter/leave burst mode.
- */
-native cs_set_weapon_burst(index, burstmode = 1);
-
-/* Returns 1 if weapon is silenced, else 0.
- */
-native cs_get_weapon_silen(index);
-
-/* If silence = 1, weapon will be silenced, 0 and silencer will be removed. Only USP and M4A1 can be silenced.
- */
-native cs_set_weapon_silen(index, silence = 1, draw_animation = 1);
-
-/* Returns amount of ammo in weapon's clip.
- */
-native cs_get_weapon_ammo(index);
-
-/* Set amount of ammo in weapon's clip.
- */
-native cs_set_weapon_ammo(index, newammo);
-
-/* Get weapon type. Corresponds to CSW_* in amxconst.inc: 1 is CSW_P228, 2 is CSW_SCOUT and so on...
- */
-native cs_get_weapon_id(index);
-
-/* Returns 1 if no knives mode is enabled, else 0.
- */
-native cs_get_no_knives();
-
-/* Enabled no knives mode by calling this with value 1. Disabled with 0.
- * No knives mode means that player will not be given a knife when spawning.
- * You can still give knives (ie through fun's give_item).
- */
-native cs_set_no_knives(noknives = 0);
-
-/* Spawns a Counter-Strike player
- */
-native cs_user_spawn(player);
-
-/* Get what weapon type (CSW_*) an armoury_entity is.
- */
-native cs_get_armoury_type(index);
-
-/* Set an armoury_entity to be of specified type. You will have to set the appropriate model.
- * The second argument, type, should be a CSW_* constant. Not all weapons are supported by Counter-strike.
- * Supported weapons/items: CSW_MP5NAVY, CSW_TMP, CSW_P90, CSW_MAC10, CSW_AK47, CSW_SG552, CSW_M4A1, CSW_AUG, CSW_SCOUT
- * CSW_G3SG1, CSW_AWP, CSW_M3, CSW_XM1014, CSW_M249, CSW_FLASHBANG, CSW_HEGRENADE, CSW_VEST, CSW_VESTHELM, CSW_SMOKEGRENADE
- */
-native cs_set_armoury_type(index, type);
-
-#define CS_MAPZONE_BUY 			(1<<0)
-#define CS_MAPZONE_BOMBTARGET 		(1<<1)
-#define CS_MAPZONE_HOSTAGE_RESCUE 	(1<<2)
-#define CS_MAPZONE_ESCAPE		(1<<3)
-#define CS_MAPZONE_VIP_SAFETY 		(1<<4)
-
-/* Returns in bitwise form if the user is in a specific map zone.
- * NOTE: If user can't plant (cs_get_user_plant(index) is 0) then cs_get_user_mapzones(index) & CS_MAPZONE_BOMBTARGET will return 0 too.
- */
-native cs_get_user_mapzones(index);
-
-/* Zoom type enum. Used for get/set_user_zoom() natives.
+/**
+ * Constants used for cs_[get|set]_user_zoom().
  */
 enum
 {
-	CS_RESET_ZOOM = 0,		// Reset any zoom blocking (when using this type, mode has no effect)
-	CS_SET_NO_ZOOM,			// Disable any sort of zoom (ie: to disable zoom in all weapons use this with mode=0)
-	CS_SET_FIRST_ZOOM,		// Set first zoom (awp style) 
-	CS_SET_SECOND_ZOOM,		// Set second zoom (awp style)
-	CS_SET_AUGSG552_ZOOM,		// Set aug/sg552 zoom style
+    CS_RESET_ZOOM = 0,      // Reset any zoom blocking (mode has no effect)
+    CS_SET_NO_ZOOM,         // Disable any sort of zoom
+    CS_SET_FIRST_ZOOM,      // Set first zoom level (AWP style)
+    CS_SET_SECOND_ZOOM,     // Set second zoom level (AWP style)
+    CS_SET_AUGSG552_ZOOM,   // Set AUG/SG552 zoom style
 };
-/* Sets a weapon zoom type on a player, any zoom type will work for all weapons, so you can even set an awp zoom to pistols :D
- * The 2nd param has to be one of the above zoom types in the enum. Mode can only be 0 or 1.
- * If mode=0 (blocking mode), the user will be forced to use the zoom type set by the native, and wont be able to change it (even by changing weapon)
- * until the native resets the zoom with CS_RESET_ZOOM.
- * If mode=1 the user will be able to restore back to a normal view by changing weapon.
+
+/**
+ * Constants used for the CS_OnBuy() and CS_OnBuyAttempt() forwards.
+ *
+ * @note While these mostly overlap with the CSW_* constants the CSI_* constants
+ *       contain custom AMXX values that do not correspond to any real value in
+ *       the game. The CSI_* constants should therefore be used for consistency.
+ */
+#define CSI_P228                CSW_P228
+#define CSI_SCOUT               CSW_SCOUT
+#define CSI_HEGRENADE           CSW_HEGRENADE
+#define CSI_XM1014              CSW_XM1014
+#define CSI_C4                  CSW_C4
+#define CSI_MAC10               CSW_MAC10
+#define CSI_AUG                 CSW_AUG
+#define CSI_SMOKEGRENADE        CSW_SMOKEGRENADE
+#define CSI_ELITE               CSW_ELITE
+#define CSI_FIVESEVEN           CSW_FIVESEVEN
+#define CSI_UMP45               CSW_UMP45
+#define CSI_SG550               CSW_SG550
+#define CSI_GALIL               CSW_GALIL
+#define CSI_FAMAS               CSW_FAMAS
+#define CSI_USP                 CSW_USP
+#define CSI_GLOCK18             CSW_GLOCK18
+#define CSI_AWP                 CSW_AWP
+#define CSI_MP5NAVY             CSW_MP5NAVY
+#define CSI_M249                CSW_M249
+#define CSI_M3                  CSW_M3
+#define CSI_M4A1                CSW_M4A1
+#define CSI_TMP                 CSW_TMP
+#define CSI_G3SG1               CSW_G3SG1
+#define CSI_FLASHBANG           CSW_FLASHBANG
+#define CSI_DEAGLE              CSW_DEAGLE
+#define CSI_SG552               CSW_SG552
+#define CSI_AK47                CSW_AK47
+#define CSI_P90                 CSW_P90
+#define CSI_SHIELDGUN           CSW_SHIELDGUN
+#define CSI_VEST                CSW_VEST        // Custom
+#define CSI_VESTHELM            CSW_VESTHELM    // Custom
+#define CSI_DEFUSER             33              // Custom
+#define CSI_NVGS                34              // Custom
+#define CSI_PRIAMMO             36              // Custom
+#define CSI_SECAMMO             37              // Custom
+
+/**
+ * Returns client's deaths.
+ *
+ * @param index     Client index
+ *
+ * @return          Client deaths
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_deaths(index);
+
+/**
+ * Sets client's deaths.
+ *
+ * @param index         Client index
+ * @param newdeaths     New value to set
+ *
+ * @noreturn
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_deaths(index, newdeaths);
+
+/**
+ * Returns index of the entity that a hostage is following.
+ *
+ * @note Hostages can theoretically follow any entity in the game, so the
+ *       returned entity index is not necessarily a client index.
+ * @note This native does not work on Condition Zero, which has a different
+ *       hostage AI than other versions of Counter-Strike.
+ *
+ * @param index     Hostage entity index
+ *
+ * @return          Entity index if hostage is following something, 0 otherwise
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
+ */
+native cs_get_hostage_foll(index);
+
+/**
+ * Sets hostage to follow an entity.
+ *
+ * @note Hostages can theoretically follow any entity in the game, so the
+ *       followedindex does not have to be a client index.
+ * @note This native does not work on Condition Zero, which has a different
+ *       hostage AI than other versions of Counter-Strike.
+ *
+ * @param index             Hostage entity index
+ * @param followedindex     New entity to follow
+ *
+ * @noreturn
+ * @error                   If the provided entity index is not a hostage, an
+ *                          error will be thrown.
+ */
+native cs_set_hostage_foll(index, followedindex = 0);
+
+/**
+ * Returns unique id of a hostage.
+ *
+ * @param index     Hostage entity index
+ *
+ * @return          Unique hostage id
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
+ */
+native cs_get_hostage_id(index);
+
+/**
+ * Returns amount of ammo in the client's backpack for a specific weapon.
+ *
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note Some weapons share ammo types and therefore ammo backpack pools. List
+ *       of ammo types:
+ *       ammo_338magnum  - awp
+ *       ammo_762nato    - scout, ak47, g3sg1
+ *       ammo_556natobox - m249
+ *       ammo_556nato    - famas, m4a1, aug, sg550, galil, sg552
+ *       ammo_buckshot   - m3, xm1014
+ *       ammo_45acp      - usp, ump45, mac10
+ *       ammo_57mm       - fiveseven, p90
+ *       ammo_50ae       - deagle
+ *       ammo_357sig     - p228
+ *       ammo_9mm        - glock, mp5, tmp, elites
+ *       /               - hegrenade
+ *       /               - flashbang
+ *       /               - smokegrenade
+ *
+ * @param index     Client index
+ * @param weapon    Weapon id
+ *
+ * @return          Amount of ammo in backpack
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, the client is not connected, or an invalid
+ *                  weapon id is provided, an error will be thrown.
+ */
+native cs_get_user_bpammo(index, weapon);
+
+/**
+ * Sets amount of ammo in the client's backpack for a specific weapon.
+ *
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note Some weapons share ammo types and therefore ammo backpack pools. List
+ *       of ammo types:
+ *       awp - ammo_338magnum
+ *       scout, ak47, g3sg1 - ammo_762nato
+ *       m249 - ammo_556natobox
+ *       famas, m4a1, aug, sg550, galil, sg552 - ammo_556nato
+ *       m3, xm1014 - ammo_buckshot
+ *       usp, ump45, mac10 - ammo_45acp
+ *       fiveseven, p90 - ammo_57mm
+ *       deagle - ammo_50ae
+ *       p228 - ammo_357sig
+ *       glock, mp5, tmp, elites - ammo_9mm
+ *       hegrenade - /
+ *       flashbang - /
+ *       smokegrenade - /
+ *
+ * @param index     Client index
+ * @param weapon    Weapon id
+ * @param amount    New backpack ammo amount to set
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, the client is not connected, or an invalid
+ *                  weapon id is provided, an error will be thrown.
+ */
+native cs_set_user_bpammo(index, weapon, amount);
+
+/**
+ * Returns if the client has a defuse kit.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client has a defuse kit, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, the client is not connected, or an invalid
+ *                  weapon id is provided, an error will be thrown.
+ */
+native cs_get_user_defuse(index);
+
+/**
+ * Sets the client's defusekit status and allows to set a custom HUD icon and
+ * color.
+ *
+ * @param index         Client index
+ * @param defusekit     If nonzero the client will have a defusekit, otherwise
+ *                      it will be removed
+ * @param r             Red component of icon color
+ * @param g             Green component of icon color
+ * @param b             Blue component of icon color
+ * @param icon          HUD sprite to use as icon
+ * @param flash         If nonzero the icon will flash red
+ *
+ * @noreturn
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_defuse(index, defusekit = 1, r = 0, g = 160, b = 0, icon[] = "defuser", flash = 0);
+
+/**
+ * Returns if the client is inside a buyzone.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client is inside a buyzone, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_buyzone(index);
+
+/**
+ * Returns if the client has a primary weapon or a shield in the inventory.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client has a primary weapon or shield in the
+ *                  inventory, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_hasprim(index);
+
+/**
+ * Retrieves the client's player model.
+ *
+ * @param index     Client index
+ * @param model     Buffer to copy model to
+ * @param len       Maximum buffer size
+ *
+ * @return          Number of cells written to buffer
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_model(index, model[], len);
+
+/**
+ * Sets the client's player model.
+ *
+ * @note This is not a one-time set. The CStrike module will remember the
+ *       selected model and try to prevent attempts at changing the player
+ *       model, or immediately re-apply it if necessary.
+ *
+ * @param index     Client index
+ * @param model     Model name
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_set_user_model(index, const model[]);
+
+/**
+ * Resets the client's model.
+ *
+ * @note This lifts the model-lock set by a previous cs_set_user_model() call.
+ *
+ * @param index     Client index
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_reset_user_model(index);
+
+/**
+ * Returns the client's amount of money.
+ *
+ * @param index     Client index
+ *
+ * @return          Amount of money
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_money(index);
+
+/**
+ * Sets the client's amount of money.
+ *
+ * @param index     Client index
+ * @param money     New amount to set
+ * @param flash     If nonzero the HUD will flash the difference between new
+ *                  and old amount in red or green
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_set_user_money(index, money, flash = 1);
+
+/**
+ * Returns if the client's has night vision goggles.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if user has NVG, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_nvg(index);
+
+/**
+ * Sets the client's night vision goggles.
+ *
+ * @param index         Client index
+ * @param nvgoogles     If nonzero the NVG will be added to the client's
+ *                      inventory, otherwise they will be removed from it
+ *
+ * @noreturn
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_nvg(index, nvgoggles = 1);
+
+/**
+ * Returns if the client has the ability to plant the bomb.
+ *
+ * @note Only with this set can the client plant the bomb within the usual bomb
+ *       target areas. If this is not set the user can not plant the bomb, even
+ *       when he has one in the inventory.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client is able to plant the bomb, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_plant(index);
+
+/**
+ * Sets the client's ability to plant the bomb and displays or hides the bomb
+ * HUD icon.
+ *
+ * @note Only with this set can the client plant the bomb within the usual bomb
+ *       target areas. If this is not set the user can not plant the bomb, even
+ *       when he has one in the inventory. This is only correctly set when the
+ *       client touches a bomb and picks it up "manually" (only possible for
+ *       Terrorists), so this should be used if the bomb is added to the
+ *       inventory through other means.
+ *
+ * @param index         Client index
+ * @param plant         If nonzero the client will be able to plant the bomb,
+ *                      otherwise he will be unable to
+ * @param showbombicon  If nonzero the green C4 icon will be displayed on the
+ *                      client's hud, otherwise it will be hidden
+ *
+ * @return              1 if the client is able to plant the bomb, 0 otherwise
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_plant(index, plant = 1, showbombicon = 1);
+
+/**
+ * Sets the client's team without killing the player, and sets the client model.
+ *
+ * @note For a list of valid team ids see the CsTeams enum, and for a list of
+ *       valid internal model ids see the CsInternalModel enum.
+ *
+ * @param index     Client index
+ * @param team      Team id
+ * @param model     Internal model id, if CS_DONTCHANGE the game will choose the
+ *                  model
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_set_user_team(index, {CsTeams,_}:team, {CsInternalModel,_}:model = CS_DONTCHANGE);
+
+/**
+ * Returns the client's team and optionally the model id.
+ *
+ * @note For a list of valid team ids see the CsTeams enum, and for a list of
+ *       valid internal model ids see the CsInternalModel enum.
+ *
+ * @param index     Client index
+ * @param model     Optional variable to store model id in
+ *
+ * @return          Team id
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native CsTeams:cs_get_user_team(index, &{CsInternalModel,_}:model = CS_DONTCHANGE);
+
+/**
+ * Returns if the client is a VIP.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client is a VIP, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_vip(index);
+
+/**
+ * Sets the client's VIP status and displayed model and scoreboard flag.
+ *
+ * @note This is mostly useful for removing VIP status so the client can change
+ *       teams and/or buy items properly. It does not alter gameplay, the player
+ *       that is selected as VIP at the start of a round will retain the
+ *       internal VIP status and remain the primary objective for the game mode.
+ *
+ * @param index         Client index
+ * @param vip           If nonzero the client will be made a VIP, otherwise the
+ *                      VIP status will be removed
+ * @param model         If nonzero the client's model will be changed to the VIP
+ *                      model, otherwise a random CT model will be selected
+ * @param scoreboard    If nonzero the scoreboard will be updated to reflect the
+ *                      new VIP status
+ *
+ * @noreturn
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_vip(index, vip = 1, model = 1, scoreboard = 1);
+
+/**
+ * Returns if the client has committed a team kill in the current round.
+ *
+ * @note If this is set to 1 the client will be punished at the start of the
+ *       next round depending on the value of the mp_tkpunish cvar. The team
+ *       kill status is then reset.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client has committed a team kill, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_tked(index);
+
+/**
+ * Sets the client's team kill status, indicating whether the client has
+ * committed a team kill in the current round.
+ *
+ * @note If this is set to 1 the client will be punished at the start of the
+ *       next round depending on the value of the mp_tkpunish cvar. The team
+ *       kill status is then reset.
+ *
+ * @param index     Client index
+ * @param tk        Team kill status
+ * @param subtract  Amount of frags to subtract, negative values add frags
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_set_user_tked(index, tk = 1, subtract = 1);
+
+/**
+ * Returns if the client is currently driving a vehicle and if so, indicates
+ * the speed.
+ *
+ * @param index     Client index
+ *
+ * @return          0 if the client is not driving, 1 if driving a vehicle but
+ *                  not moving, 2 to 4 if driving positive speeds, 5 if
+ *                  driving at a negative speed (backing)
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_driving(index);
+
+/**
+ * Returns if the client has a shield in the inventory.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client has a shield, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_shield(index);
+
+/**
+ * Returns if the client is using a stationary gun.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if the client uses a stationary gun, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_stationary(index);
+
+/**
+ * Returns the client's armor value and retrieves the type of armor.
+ *
+ * @note For a list of possible armor types see the CsArmorType enum.
+ *
+ * @param index         Client index
+ * @param armortype     Variable to store armor type in
+ *
+ * @return              Amount of armor, 0 if client has no armor
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_get_user_armor(index, &CsArmorType:armortype);
+
+/**
+ * Sets the client's armor value the type of armor.
+ *
+ * @note For a list of possible armor types see the CsArmorType enum.
+ * @note Sends the appropriate message to update the client's HUD.
+ *
+ * @param index         Client index
+ * @param armorvalue    Amount of armor to set
+ * @param armortype     CS armor type
+ *
+ * @noreturn
+ * @error               If the client index is not within the range of 1 to
+ *                      MaxClients, or the client is not connected, an error
+ *                      will be thrown.
+ */
+native cs_set_user_armor(index, armorvalue, CsArmorType:armortype);
+
+/**
+ * Returns if the weapon is in burst mode.
+ *
+ * @note Only the Glock and Famas can return 1 as they are the only guns in the
+ *       game that have a burst fire mode.
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will return incorrect values for non-weapon entities.
+ *
+ * @param index     Weapon entity index
+ *
+ * @return          1 if the weapon is in burst mode, 0 otherwise
+ * @error           If an invalid entity index or a client index is provided,
+ *                  an error will be thrown.
+ */
+native cs_get_weapon_burst(index);
+
+/**
+ * Sets the weapon's burst mode.
+ *
+ * @note Only the Glock and Famas can be set to burst fire mode as they are the
+ *       only guns in the game that provide such a mode.
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will result in undefined behavior if used on
+ *       non-weapon entities.
+ *
+ * @param index         Weapon entity index
+ * @param burstmode     If nonzero the weapon will be put into burstmode,
+ *                      otherwise the burst mode will be removed
+ *
+ * @return              1 if burst mode set successfully, 0 if entity is not
+ *                      an applicable weapon
+ * @error               If an invalid entity index or a client index is
+ *                      provided, an error will be thrown.
+ */
+native cs_set_weapon_burst(index, burstmode = 1);
+
+/**
+ * Returns if the weapon is in silenced mode.
+ *
+ * @note Only the USP and M4A1 can return 1 as they are the only guns in the
+ *       game that have a silenced fire mode.
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will return incorrect values for non-weapon entities.
+ *
+ * @param index     Weapon entity index
+ *
+ * @return          1 if the weapon is in silenced mode, 0 otherwise
+ * @error           If an invalid entity index or a client index is provided,
+ *                  an error will be thrown.
+ */
+native cs_get_weapon_silen(index);
+
+/**
+ * Sets the weapon's silenced mode.
+ *
+ * @note Only the USP and M4A1 can be set to silenced fire mode as they are the
+ *       only guns in the game that provide such a mode.
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will result in undefined behavior if used on
+ *       non-weapon entities.
+ *
+ * @param index             Weapon entity index
+ * @param silence           If nonzero the weapon will be put into silenced
+ *                          mode, otherwise the silenced mode will be removed
+ * @param draw_animation    If nonzero and the weapon is currently held by a
+ *                          client, the appropriate weapon animation will be
+ *                          played
+ *
+ * @return                  1 if silenced mode set successfully, 0 if entity is
+ *                          not an applicable weapon
+ * @error                   If an invalid entity index or a client index is
+ *                          provided, an error will be thrown.
+ */
+native cs_set_weapon_silen(index, silence = 1, draw_animation = 1);
+
+/**
+ * Returns the amount of ammo in weapon's magazine.
+ *
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will return incorrect values for non-weapon entities.
+ *
+ * @param index     Weapon entity index
+ *
+ * @return          Amount of ammo in magazine
+ * @error           If an invalid entity index or a client index is provided,
+ *                  an error will be thrown.
+ */
+native cs_get_weapon_ammo(index);
+
+/**
+ * Sets the amount of ammo in weapon's clip.
+ *
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will result in undefined behavior if used on
+ *       non-weapon entities.
+ *
+ * @param index     Weapon entity index
+ * @param newammo   New ammo amount
+ *
+ * @noreturn
+ * @error           If an invalid entity index or a client index is provided,
+ *                  an error will be thrown.
+ */
+native cs_set_weapon_ammo(index, newammo);
+
+/**
+ * Returns the weapon id of an entity.
+ *
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note This native does not check that the provided entity is actually a
+ *       weapon entity. It will return incorrect values for non-weapon entities.
+ *
+ * @param index     Weapon entity index
+ *
+ * @return          Weapon id
+ * @error           If an invalid entity index or a client index is provided,
+ *                  an error will be thrown.
+ */
+native cs_get_weapon_id(index);
+
+/**
+ * Returns if "no knives" mode is enabled.
+ *
+ * @note "No knives" mode means that the CStrike module will prevent the game
+ *       from creating (and thus attaching) "weapon_knife" entities. This means
+ *       that clients will spawn without knives, but knives can still be put
+ *       into the client inventories directly.
+ *
+ * @return  1 if "no knives" mode is enabled, 0 otherwise
+ */
+native cs_get_no_knives();
+
+/**
+ * Enables or disables the "no knives" mode.
+ *
+ * @note "No knives" mode means that the CStrike module will prevent the game
+ *       from creating (and thus attaching) "weapon_knife" entities. This means
+ *       that clients will spawn without knives, but knives can still be put
+ *       into the client inventories directly.
+ *
+ * @param noknives  If nonzero enable "no knives" mode, disable otherwise
+ *
+ * @noreturn
+ */
+native cs_set_no_knives(noknives = 0);
+
+/**
+ * Sets a dead client up for spawning.
+ *
+ * @note This sets the client deadflag and triggers a client think, effectively
+ *       making the game respawn the client. Should only be used on dead
+ *       clients.
+ *
+ * @param player    Client index
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_user_spawn(player);
+
+/**
+ * Returns the armoury entity's weapon id.
+ *
+ * @note Not all weapon ids are supported by Counter-Strike, an armoury entity
+ *       can not be a pistol, a knife or a bomb for exmaple. The full list is:
+ *          CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG,
+ *          CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1,
+ *          CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG,
+ *          CSW_SG552, CSW_AK47, CSW_P90
+ *
+ * @param index     Armoury entity index
+ *
+ * @return          Weapon id
+ * @error           If a non-armoury entity is provided, an error will be
+ *                  thrown.
+ */
+native cs_get_armoury_type(index);
+
+/**
+ * Sets the amoury entity type.
+ *
+ * @note Not all weapon ids are supported by Counter-Strike, an armoury entity
+ *       can not be a pistol, a knife or a bomb for exmaple. The full list is:
+ *          CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG,
+ *          CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1,
+ *          CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG,
+ *          CSW_SG552, CSW_AK47, CSW_P90
+ * @note This does not update the entity model.
+ *
+ * @param index     Armoury entity index
+ * @param type      Weapon id
+ *
+ * @noreturn
+ * @error           If a non-armoury entity is provided, an error will be
+ *                  thrown.
+ */
+native cs_set_armoury_type(index, type);
+
+/**
+ * Returns the map zones the client is inside of as a bitflag value.
+ *
+ * @note If the user does not have the ability to plant (cs_get_user_plant()
+ *       returns 0) then the bitflag will not contain CS_MAPZONE_BOMBTARGET.
+ * @nore For a list of possible zone flags see the CS_MAPZONE_* constants.
+ *
+ * @param index     Client index
+ *
+ * @return          Bitflag value of map zones
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
+ */
+native cs_get_user_mapzones(index);
+
+/**
+ * Sets a zoom type on the client.
+ *
+ * @note Zoom types are not tied to their intended weapons, so any zoom type can
+ *       be combined with any weapon.
+ * @note For a list of possible zoom types see the zoom type enum above
+ *       (CS_*_ZOOM constants).
+ *
+ * @param index     Client index
+ * @param type      Zoom type
+ * @param mode      If zero (blocking) the client will be forced to use the zoom
+ *                  type set and won't be able to change it until it is reset
+ *                  with CS_RESET_ZOOM, otherwise the user can restore back to
+ *                  normal as usual
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, the client is not connected, or an invalid zoom
+ *                  type is provided, an error will be thrown.
  */
 native cs_set_user_zoom(index, type, mode);
 
-/* Returns how a user is zooming during the native call. Values correspond to the above enum, but will return 0 if an error occurred.
+/**
+ * Returns if the client is zooming.
+ *
+ * @note For a list of possible zoom types see the zoom type enum above
+ *       (CS_*_ZOOM constants).
+ *
+ * @param index     Client index
+ *
+ * @return          Zoom type if the user is zoomed in, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
  */
 native cs_get_user_zoom(index);
 
-/* Returns the submodel setting of the player.
- * If this is 1, then the user has a backpack or defuser on their model (depending on team)
+/**
+ * Returns if a submodel is set on the client.
+ *
+ * @note In Counter-Strike the submodel setting determines whether the user has
+ *       a bomb backpack (if a Terrorist) or a defuse kit (if a CT) on their
+ *       model.
+ *
+ * @param index     Client index
+ *
+ * @return          1 if submodel is set, 0 otherwise
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ *                  thrown.
  */
 native cs_get_user_submodel(index);
 
-/* Sets the submodel setting of the player.
- * If this is 1, then the user has a backpack or defuser on their model (depending on team)
- * 0 removes it.
+/**
+ * Sets the submodel on a client.
+ *
+ * @note In Counter-Strike the submodel setting determines whether the user has
+ *       a bomb backpack (if a Terrorist) or a defuse kit (if a CT) on their
+ *       model.
+ *
+ * @param index     Client index
+ * @param value     If nonzero the submodel is set, otherwise it is removed
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
  */
 native cs_set_user_submodel(index, value);
 
-/* Gets or sets the user's last activity time.  This is the time that CS's internal afk kicker
- * checks to see who has been afk too long.
+/**
+ * Returns the client's last activity time.
+ *
+ * @note This is the time that the internal Counter-Strike afk kicker uses to
+ *       see who has been inactive too long.
+ *
+ * @param index     Client index
+ *
+ * @return          Last activity time
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
  */
 native Float:cs_get_user_lastactivity(index);
 
+/**
+ * Sets the client's last activity time.
+ *
+ * @note This is the time that the internal Counter-Strike afk kicker uses to
+ *       see who has been inactive too long.
+ *
+ * @param index     Client index
+ * @param value     New last activity time
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ */
 native cs_set_user_lastactivity(index, Float:value);
 
-/* Gets or sets the number of hostages that a user has killed.
+/**
+ * Returns the amount of hostages that the client has killed.
+ *
+ * @note This is the value that the internal Counter-Strike hostage punisher
+ *       uses to determine if a client should be kicked, depending on the
+ *       value of the mp_hostagepenalty value.
+ *
+ * @param index     Client index
+ *
+ * @return          Amount of hostages killed
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
  */
 native cs_get_user_hostagekills(index);
 
+/**
+ * Sets the amount of hostages that the client has killed.
+ *
+ * @note This is the value that the internal Counter-Strike hostage punisher
+ *       uses to determine if a client should be kicked, depending on the
+ *       value of the mp_hostagepenalty value. The punisher only checks this
+ *       value when a hostage is actually killed, so setting this will not cause
+ *       a client to be kicked until they actually kill a hostage.
+ *
+ * @param index     Client index
+ * @param value     New amount of hostages killed
+ *
+ * @noreturn
+ * @error           If the client index is not within the range of 1 to
+ *                  MaxClients, or the client is not connected, an error will be
+ */
 native cs_set_user_hostagekills(index, value);
 
-/* Gets or sets the time that the hostage was last used.
+/**
+ * Returns the last time a hostage was used.
+ *
+ * @param index     Hostage entity
+ *
+ * @return          Last use time
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
  */
 native Float:cs_get_hostage_lastuse(index);
 
+/**
+ * Sets the last time a hostage was used.
+ *
+ * @param index     Hostage entity
+ * @param value     New last use time
+ *
+ * @noreturn
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
+ */
 native cs_set_hostage_lastuse(index, Float:value);
 
-/* Gets or sets the time which the hostage can next be used.
+/**
+ * Returns the next time a hostage can be used.
+ *
+ * @param index     Hostage entity
+ *
+ * @return          Next use time
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
  */
 native Float:cs_get_hostage_nextuse(index);
 
+/**
+ * Sets the next time a hostage can be used.
+ *
+ * @param index     Hostage entity
+ * @param value     New next use time
+ *
+ * @noreturn
+ * @error           If the provided entity index is not a hostage, an error will
+ *                  be thrown.
+ */
 native cs_set_hostage_nextuse(index, Float:value);
 
-/* Gets or sets the time in which the C4 will explode.
+/**
+ * Returns the time the bomb will explode.
+ *
+ * @param index     C4 entity
+ *
+ * @return          Explosion time
+ * @error           If the provided entity index is not a bomb, an error will be
+ *                  thrown.
  */
 native Float:cs_get_c4_explode_time(index);
 
+/**
+ * Sets the time the bomb will explode.
+ *
+ * @param index     C4 entity
+ * @param value     New explosion time
+ *
+ * @noreturn
+ * @error           If the provided entity index is not a bomb, an error will be
+ *                  thrown.
+ */
 native cs_set_c4_explode_time(index, Float:value);
 
-/* Gets or sets whether the C4 is being defused.
+/**
+ * Returns if the bomb is being defused.
+ *
+ * @param index     C4 entity
+ *
+ * @return          1 if the bomb is being defused, 0 otherwise
+ * @error           If the provided entity index is not a bomb, an error will be
+ *                  thrown.
  */
 native bool:cs_get_c4_defusing(c4index);
 
+/**
+ * Sets if the bomb is being defused.
+ *
+ * @param index     C4 entity
+ * @param defusing  True if the bomb should be defused, false otherwise
+ *
+ * @noreturn
+ * @error           If the provided entity index is not a bomb, an error will be
+ *                  thrown.
+ */
 native cs_set_c4_defusing(c4index, bool:defusing);
 
 /**
@@ -369,7 +1100,7 @@ native cs_set_c4_defusing(c4index, bool:defusing);
  *
  * @param classname     Entity class name
  *
- * @return              Index of the created entity, 0 otherwise.
+ * @return              Index of the created entity (> 0), 0 otherwise
  */
 native cs_create_entity(const classname[]);
 
@@ -393,74 +1124,46 @@ native cs_create_entity(const classname[]);
 native cs_find_ent_by_class(start_index, const classname[]);
 
 /**
- * Called when CS internally fires a command to a player.  It does this for a few 
- * functions, most notably rebuy/autobuy functionality.  This is also used to pass
- * commands to CZ bots internally.
+ * Called when CS internally fires a command to a player.
  *
- * @param id			Client index.
- * @param cmd			Command string.
- * @return				PLUGIN_HANDLED to block, PLUGIN_CONTINUE for normal operation.
+ * @note This is most notably used by the rebuy/autobuy functionality,
+ *       Condition Zero also uses this to pass commands to bots internally.
+ *
+ * @param id    Client index
+ * @param cmd   Command string
+ *
+ * @return      PLUGIN_CONTINUE to let the command continue
+ *              PLUGIN_HANDLED to block the command
  */
 forward CS_InternalCommand(id, const cmd[]);
 
-
 /**
- * The following constants are used with CS_OnBuy[Attempt] forwards.
- */
-#define CSI_P228				CSW_P228
-#define CSI_SCOUT				CSW_SCOUT
-#define CSI_HEGRENADE			CSW_HEGRENADE
-#define CSI_XM1014				CSW_XM1014
-#define CSI_C4					CSW_C4
-#define CSI_MAC10				CSW_MAC10
-#define CSI_AUG					CSW_AUG
-#define CSI_SMOKEGRENADE		CSW_SMOKEGRENADE
-#define CSI_ELITE				CSW_ELITE
-#define CSI_FIVESEVEN			CSW_FIVESEVEN
-#define CSI_UMP45				CSW_UMP45
-#define CSI_SG550				CSW_SG550
-#define CSI_GALIL				CSW_GALIL
-#define CSI_FAMAS				CSW_FAMAS
-#define CSI_USP					CSW_USP
-#define CSI_GLOCK18				CSW_GLOCK18
-#define CSI_AWP					CSW_AWP
-#define CSI_MP5NAVY				CSW_MP5NAVY
-#define CSI_M249				CSW_M249
-#define CSI_M3					CSW_M3
-#define CSI_M4A1				CSW_M4A1
-#define CSI_TMP					CSW_TMP
-#define CSI_G3SG1				CSW_G3SG1
-#define CSI_FLASHBANG			CSW_FLASHBANG
-#define CSI_DEAGLE				CSW_DEAGLE
-#define CSI_SG552				CSW_SG552
-#define CSI_AK47				CSW_AK47
-#define CSI_P90					CSW_P90
-#define CSI_SHIELDGUN			CSW_SHIELDGUN
-#define CSI_VEST				CSW_VEST		// Custom
-#define CSI_VESTHELM			CSW_VESTHELM	// Custom
-#define CSI_DEFUSER				33				// Custom
-#define CSI_NVGS				34				// Custom
-#define CSI_PRIAMMO				36				// Custom
-#define CSI_SECAMMO				37				// Custom
-
-/**
- * Called when a player attempts to purchase an item.
- * This is ususally called right away on buy commands issued by a player.
- * 
- * @note Return PLUGIN_CONTINUE to allow the purchase or return a higher action to deny.
+ * Called when a client attempts to purchase an item.
  *
- * @param index			Player index.
- * @param item			Item index, see CSI_* constants.
+ * @note This is called immediately when the client issues a buy command. The
+ *       game has not actually checked if the client can actually buy the
+ *       weapon.
+ * @note For a list of possible item ids see the CSI_* constants.
+ *
+ * @param index     Client index
+ * @param item      Item id
+ *
+ * @return          PLUGIN_CONTINUE to let the buy attempt continue
+ *                  PLUGIN_HANDLED to block the buy attempt
  */
 forward CS_OnBuyAttempt(index, item);
 
 /**
- * Called when a player purchases an item.
- * This usually called right before a player gets the purchased item.
+ * Called when a client purchases an item.
  *
- * @note Return PLUGIN_CONTINUE to allow the purchase or return a higher action to deny.
+ * @note This is called right before the user receives the item and before the
+ *       money is deducted from their cash reserves.
+ * @note For a list of possible item ids see the CSI_* constants.
  *
- * @param index			Player index.
- * @param item			Item index, see CSI_* constants.
+ * @param index     Client index
+ * @param item      Item id
+ *
+ * @return          PLUGIN_CONTINUE to let the buy continue
+ *                  PLUGIN_HANDLED to block the buy
  */
 forward CS_OnBuy(index, item);
diff --git a/plugins/include/csx.inc b/plugins/include/csx.inc
index 3616d178..70d90883 100755
--- a/plugins/include/csx.inc
+++ b/plugins/include/csx.inc
@@ -27,65 +27,237 @@
  #pragma library csx
 #endif
 
-/*
- * Forwards
+/**
+ * Map objective flags returned by get_map_objectives().
  */
-
-/* Function is called after player to player attacks ,
-* if players were damaged by teammate TA is set to 1 */
-forward client_damage(attacker,victim,damage,wpnindex,hitplace,TA);
-
-/* Function is called after player death ,
-* if player was killed by teammate TK is set to 1 */
-forward client_death(killer,victim,wpnindex,hitplace,TK);
-
-forward grenade_throw( index,greindex,wId );
-
-forward bomb_planting(planter);
-forward bomb_planted(planter);
-forward bomb_explode(planter,defuser);
-forward bomb_defusing(defuser);
-forward bomb_defused(defuser);
-
-/************* Shared Natives Start ********************************/
-
-/* Custom Weapon Support */
-/* function will return index of new weapon */
-native custom_weapon_add( const wpnname[],melee = 0,const logname[]="" ); 
-/* Function will pass damage done by this custom weapon to stats module and other plugins */
-native custom_weapon_dmg( weapon, att, vic, damage, hitplace=0 ); 
-/* Function will pass info about custom weapon shot to stats module */
-native custom_weapon_shot( weapon,index ); // weapon id , player id
-
-/* function will return 1 if true */
-native xmod_is_melee_wpn(wpnindex);
-
-/* Returns weapon name. */
-native xmod_get_wpnname(wpnindex,name[],len);
-
-/* Returns weapon logname. */
-native xmod_get_wpnlogname(wpnindex,name[],len);
-
-/* Returns weapons array size */
-native xmod_get_maxweapons();
-
-/* Returns stats array size */
-native xmod_get_stats_size();
-
-/************* Shared Natives End ********************************/
-
 enum MapObjective
 {
-	MapObjective_Bomb	 = (1<<0),
-	MapObjective_Hostage = (1<<1),
-	MapObjective_Vip	 = (1<<2),
-	MapObjective_Escape  = (1<<3),
+    MapObjective_Bomb    = (1<<0),
+    MapObjective_Hostage = (1<<1),
+    MapObjective_Vip     = (1<<2),
+    MapObjective_Escape  = (1<<3),
 };
 
 /**
- * Gets current map objectives.
+ * Called after a client attacks another client.
  *
- * @return 		Returns a bits sum if objectives are found, otherwise 0. 
- * 				See MapObjective_* constants.
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param attacker  Attacker client index
+ * @param victim    Victim client index
+ * @param damage    Damage dealt to victim
+ * @param wpnindex  Weapon id
+ * @param hitplace  Body hitplace
+ * @param ta        If nonzero the attack was a team attack
+ *
+ * @noreturn
+ */
+forward client_damage(attacker, victim, damage, wpnindex, hitplace, TA);
+
+/**
+ * Called after a client death.
+ *
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param attacker  Attacker client index
+ * @param victim    Victim client index
+ * @param wpnindex  Weapon id
+ * @param hitplace  Body hitplace
+ * @param tk        If nonzero the death was a teamkill
+ *
+ * @noreturn
+ */
+forward client_death(killer, victim, wpnindex, hitplace, TK);
+
+/**
+ * Called after a grenade was thrown.
+ *
+ * @note Weapon id is one of CSW_HEGRENADE, CSW_SMOKEGRENADE or CSW_FLASHBANG.
+ *
+ * @param index     Client index
+ * @param greindex  Grenade entity index
+ * @param wId       Weapon id
+ *
+ * @noreturn
+ */
+forward grenade_throw(index, greindex, wId);
+
+/**
+ * Called after a bomb plant attempt has started.
+ *
+ * @param planter   Planter client index
+ *
+ * @noreturn
+ */
+forward bomb_planting(planter);
+
+/**
+ * Called after a bomb plant has finished.
+ *
+ * @param planter   Planter client index
+ *
+ * @noreturn
+ */
+forward bomb_planted(planter);
+
+/**
+ * Called when the bomb exploded.
+ *
+ * @param planter   Planter client index
+ * @param defuser   Defuser client index, if applicable
+ *
+ * @noreturn
+ */
+forward bomb_explode(planter, defuser);
+
+/**
+ * Called after a bomb defuse attempt has started.
+ *
+ * @param defuser   Defuser client index
+ *
+ * @noreturn
+ */
+forward bomb_defusing(defuser);
+
+/**
+ * Called after a bomb defuse has finished.
+ *
+ * @param defuser   Defuser client index
+ *
+ * @noreturn
+ */
+forward bomb_defused(defuser);
+
+/**
+ * @section Shared natives
+ */
+
+/**
+ * Adds a custom weapon to the stats system.
+ *
+ * @note The weapon name should be the full display name of the gun such as
+ *       "Desert Eagle" while the logname should be "weapon_deagle".
+ *
+ * @param wpnname   Full weapon name
+ * @param melee     If nonzero the weapon will be considered a melee weapon
+ * @param logname   Weapon short name
+ *
+ * @return          Cusom weapon id (>0) on success, 0 if no more custom weapons
+ *                  can be added
+ */
+native custom_weapon_add(const wpnname[], melee = 0, const logname[] = "");
+
+/**
+ * Trigger a damage event on a custom weapon, adding it to the internal stats.
+ *
+ * @note This will also call the client_damage() and client_kill() forwards if
+ *       applicable.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param weapon    Custom weapon id
+ * @param att       Attacker client index
+ * @param vic       Victim client index
+ * @param damage    Damage dealt
+ * @param hitplace  Optional body hitplace
+ *
+ * @noreturn
+ * @error           If the weapon id is not a custom weapon, an invalid client
+ *                  index, damage value or hitplace is provided, an error will
+ *                  be thrown.
+ */
+native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0);
+
+/**
+ * Add a shot event on a custom weapon to the internal stats.
+ *
+ * @param weapon    Custom weapon id
+ * @param index     Client index
+ *
+ * @noreturn
+ * @error           If the weapon id is not a custom weapon or an invalid client
+ *                  index is provided, an error will be thrown.
+ */
+native custom_weapon_shot(weapon, index); // weapon id , player id
+
+/**
+ * Returns if the weapon is considered a melee weapon.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ *
+ * @return          1 if weapon is a melee weapon, 0
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_is_melee_wpn(wpnindex);
+
+/**
+ * Retrieves the full weapon name of a weapon id.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ * @param name      Buffer to copy weapon name to
+ * @param len       Maximmum buffer size
+ *
+ * @return          Number of cells written to buffer
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_get_wpnname(wpnindex, name[], len);
+
+/**
+ * Retrieves the weapon log name of a weapon id.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ * @param name      Buffer to copy weapon log name to
+ * @param len       Maximmum buffer size
+ *
+ * @return          Number of cells written to buffer
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_get_wpnlogname(wpnindex, name[], len);
+
+/**
+ * Returns the maximum amount of weapons that the stats system supports.
+ *
+ * @return      Maximum number of weapons supported
+ */
+native xmod_get_maxweapons();
+
+/**
+ * Returns the number of stats tracked by the stats system.
+ *
+ * @return      Number of stats tracked
+ */
+native xmod_get_stats_size();
+
+/**
+ * @endsection Shared natives
+ */
+
+/**
+ * Returns the current map's objectives as a bitflag value.
+ *
+ * @note For a list of possible map objective flags see the MapObjective enum.
+ *
+ * @return      Bitflag value of map objectives
  */
 native MapObjective:get_map_objectives();

From 828d9971a4a43559cb44913c43406809f6471be1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Fri, 20 Feb 2015 15:35:06 +0100
Subject: [PATCH 06/10] cvars: Style touchups, add missing stuff, update notes
 about named access

---
 plugins/include/cvars.inc | 281 +++++++++++++++++++++-----------------
 1 file changed, 152 insertions(+), 129 deletions(-)

diff --git a/plugins/include/cvars.inc b/plugins/include/cvars.inc
index bc256fb4..38cca88c 100644
--- a/plugins/include/cvars.inc
+++ b/plugins/include/cvars.inc
@@ -13,39 +13,56 @@
 #define _cvars_included
 
 /**
- * CVAR flags for create_cvar()
+ * CVAR flags for create_cvar() and register_cvar().
  */
-#define FCVAR_NONE              0   /* No flags */
-#define FCVAR_ARCHIVE           1   /* Set to cause it to be saved to vars.rc */
-#define FCVAR_USERINFO          2   /* Changes the client's info string */
-#define FCVAR_SERVER            4   /* Notifies players when changed */
-#define FCVAR_EXTDLL            8   /* Defined by external DLL */
-#define FCVAR_CLIENTDLL         16  /* Defined by the client dll */
-#define FCVAR_PROTECTED         32  /* It's a server cvar, but we don't send the data since it's a password, etc.  Sends 1 if it's not bland/zero, 0 otherwise as value */
-#define FCVAR_SPONLY            64  /* This cvar cannot be changed by clients connected to a multiplayer server. */
-#define FCVAR_PRINTABLEONLY     128 /* This cvar's string cannot contain unprintable characters ( e.g., used for player name etc ). */
-#define FCVAR_UNLOGGED          256 /* If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */
-#define FCVAR_NOEXTRAWHITEPACE  512 /* Strip trailing/leading white space from this cvar */
+#define FCVAR_NONE              0   // No special behavior
+#define FCVAR_ARCHIVE           1   // Cvar will be saved to vars.rc Set to cause it to be saved to vars.rc
+#define FCVAR_USERINFO          2   // Cvar changes the client's info string
+#define FCVAR_SERVER            4   // Clients get notified when cvar value is changed
+#define FCVAR_EXTDLL            8   // Defined by an external DLL
+#define FCVAR_CLIENTDLL         16  // Defined by the client DLL
+#define FCVAR_PROTECTED         32  // Cvar value is masked from outside access, should be used for sensitive cvars like passwords
+#define FCVAR_SPONLY            64  // Cvar can't be changed by clients connected to a multiplayer server
+#define FCVAR_PRINTABLEONLY     128 // The cvar string value can not contain unprintable characters
+#define FCVAR_UNLOGGED          256 // If the cvar is FCVAR_SERVER, don't log changes to a file/the console
+#define FCVAR_NOEXTRAWHITEPACE  512 // Automatically strips trailing/leading white space from the string value
+
+/**
+ * Cvar bound constants used with [get|set]_pcvar_bounds().
+ */
+enum CvarBounds
+{
+    CvarBound_Upper = 0,
+    CvarBound_Lower
+};
 
 /**
  * Creates a new cvar for the engine.
  *
- * @note This has the same effect as register_cvar but provides more options.
+ * @note This has the same effect as register_cvar() but provides more options.
  * @note For a list of possible cvar flags see FCVAR_* constants above.
  * @note If an already existing cvar is registered it will not be duplicated.
+ *       The default value is only set when the cvar is registered for the very
+ *       first time since the server was started. Cvar bounds are overwritten
+ *       by the create_cvar() call just as if they were re-set using
+ *       set_pcvar_bounds().
  * @note The returned cvar pointer should be used with the get_pcvar_* and
  *       set_pcvar_* set of functions.
  *
- * @param name        Cvar name
- * @param string      Default cvar value
- * @param flags       Optional bitsum of flags specifying cvar behavior
- * @param description Optional description of the cvar
- * @param has_min     Optional boolean that specifies if the cvar has a minimum value
- * @param min_val     Minimum floating point value
- * @param has_max     Optional boolean that specifies if the cvar has a maximum value
- * @param max_val     Maximum floating point value
+ * @param name          Cvar name
+ * @param string        Default cvar value
+ * @param flags         Optional bitsum of flags specifying cvar behavior
+ * @param description   Optional description of the cvar
+ * @param has_min       Optional boolean that specifies if the cvar has a
+ *                      minimum value
+ * @param min_val       Minimum floating point value
+ * @param has_max       Optional boolean that specifies if the cvar has a
+ *                      maximum value
+ * @param max_val       Maximum floating point value
  *
- * @return          Unique cvar pointer
+ * @return              Unique cvar pointer
+ * @error               If invalid bounds are provided (min_val > max_val or
+ *                      vice versa), an error will be thrown.
  */
 native create_cvar(const name[], const string[], flags = FCVAR_NONE, const description[] = "", bool:has_min = false, Float:min_val = 0.0, bool:has_max = false, Float:max_val = 0.0);
 
@@ -55,6 +72,8 @@ native create_cvar(const name[], const string[], flags = FCVAR_NONE, const descr
  * @note Deprecated. Consider to use create_cvar for more options.
  * @note For a list of possible cvar flags see FCVAR_* constants in amxconst.inc
  * @note If an already existing cvar is registered it will not be duplicated.
+ *       The default value is only set when the cvar is registered for the very
+ *       first time since the server was started.
  * @note The returned cvar pointer should be used with the get_pcvar_* and
  *       set_pcvar_* set of functions.
  *
@@ -65,7 +84,7 @@ native create_cvar(const name[], const string[], flags = FCVAR_NONE, const descr
  *
  * @return          Unique cvar pointer
  */
-native register_cvar(const name[], const string[], flags = FCVAR_NONE, Float:fvalue=0.0);
+native register_cvar(const name[], const string[], flags = FCVAR_NONE, Float:fvalue = 0.0);
 
 /**
  * Returns if a cvar is registered on the server.
@@ -79,8 +98,9 @@ native cvar_exists(const cvar[]);
 /**
  * Returns the cvar pointer of the specified cvar.
  *
- * @note A pointer is also returned by register_cvar(). Plugins can (and should)
- *       retrieve and use pointers for already existing mod cvars.
+ * @note A pointer is also returned by register_cvar() and create_cvar().
+ *       Plugins can (and should) retrieve and use pointers for already existing
+ *       mod cvars.
  *
  * @param cvar      Cvar name to find
  *
@@ -93,56 +113,59 @@ native get_cvar_pointer(const cvar[]);
  *
  * @note Changing the cvar value from within this forward can lead to infinite
  *       recursion and should be avoided.
- * @note Callback will be called in the following manner:
+ * @note The callback will be called in the following manner:
  *
- *       public cvar_change_callback(pcvar, const old_value[], const new_value[])
+ * public cvar_change_callback(pcvar, const old_value[], const new_value[])
  *
- *       pcvar         - Pointer to cvar that was changed
- *       old_value     - String containing the value of the cvar before it was changed
- *       new_value     - String containing the new value of the cvar
+ *   pcvar         - Pointer to cvar that was changed
+ *   old_value     - Buffer containing the previous value of the cvar
+ *   new_value     - Buffer containing the new value of the cvar
  *
- *       The return value is ignored
+ * The return value is ignored
  *
- * @param pcvar         Pointer to cvar
- * @param callback      Name of callback function
+ * @param pcvar     Pointer to cvar
+ * @param callback  Name of callback function
  *
- * @return              Callback handle that can be used with [disable|enable]_cvar_hook
- * @error               Invalid cvar pointer or invalid callback function
+ * @return          Callback handle that can be used with
+ *                  [disable|enable]_cvar_hook
+ * @error           If an invalid cvar pointer or callback function is provided,
+ *                  an error will be thrown.
  */
 native cvarhook:hook_cvar_change(pcvar, const callback[]);
 
 /**
- * Stops a cvar hook forward from triggering.
+ * Disables a cvar hook, stopping it from being called.
  *
- * @note  Use the handle returned by hook_cvar_change as the parameter here.
+ * @note Use the handle returned by hook_cvar_change as the parameter here.
  *
- * @param handle        Forward to stop
- * @error               Invalid hook handle
+ * @param handle    Forward to disable
+ * @error           If an invalid hook handle is provided, an error will be
+ *                  thrown.
  */
 native disable_cvar_hook(cvarhook:handle);
 
 /**
- * Starts a cvar hook forward back up.
+ * Enables a cvar hook, restoring it to being called.
  *
- * @note  Use the handle returned by hook_cvar_change as the parameter here.
+ * @note Use the handle returned by hook_cvar_change as the parameter here.
  *
- * @param handle        Forward to back up
- * @error               Invalid hook handle
+ * @param handle    Forward to enable
+ * @error           If an invalid hook handle is provided, an error will be
+ *                  thrown.
  */
 native enable_cvar_hook(cvarhook:handle);
 
 /**
- * Returns flags of a cvar. The cvar is accessed by name.
+ * Returns a flags of a cvar. The cvar is accessed by name.
  *
  * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the get_pcvar_flags function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent get_pcvar_flags() function should be used
+ *       instead.
  *
- * @param cvar      Cvar name to retrieve flags from
+ * @param cvar  Cvar name to retrieve flags from
  *
- * @return          1 on success, 0 if cvar does not exist or is not permitted
+ * @return      Flag value
  */
 native get_cvar_flags(const cvar[]);
 
@@ -154,10 +177,9 @@ native get_cvar_flags(const cvar[]);
  * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
  * @note This function just adds the flags using a bitwise-or operation. After
  *       it has run the flags may not exactly equal the specified bitflag sum.
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the set_pcvar_flags function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent set_pcvar_flags() function should be used
+ *       instead.
  *
  * @param cvar      Cvar name to remove flags from
  * @param flags     Bitflag sum of flags to set
@@ -173,11 +195,8 @@ native set_cvar_flags(const cvar[], flags);
  *       and "sv_cheats" cvars.
  * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
  * @note This function removes the flags using a bitwise-and operation.
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the set_pcvar_flags function.
- *
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the set_pcvar_flags() function should be used instead.
  *
  * @param cvar      Cvar name to remove flags from
  * @param flags     Bitflag sum of flags to remove
@@ -189,10 +208,9 @@ native remove_cvar_flags(const cvar[], flags=-1);
 /**
  * Gets a string value from a cvar. The cvar is accessed by name.
  *
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the get_pcvar_string function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent get_pcvar_string() function should be used
+ *       instead.
  *
  * @param cvar      Cvar name to retrieve value from
  * @param output    Buffer to copy cvar value to
@@ -205,10 +223,9 @@ native get_cvar_string(const cvarname[], output[], iLen);
 /**
  * Sets a cvar to a given string value. The cvar is accessed by name.
  *
- * @note Accessing a cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the set_pcvar_string function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent set_pcvar_string() function should be used
+ *       instead.
  *
  * @param cvar      Cvar name to set value of
  * @param value     Value to set cvar to
@@ -220,10 +237,9 @@ native set_cvar_string(const cvar[], const value[]);
 /**
  * Returns a floating value from a cvar. The cvar is accessed by name.
  *
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the get_pcvar_float function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent get_pcvar_float() function should be used
+ *       instead.
  *
  * @param cvarname  Cvar name to retrieve value from
  *
@@ -234,10 +250,9 @@ native Float:get_cvar_float(const cvarname[]);
 /**
  * Sets a cvar to a given float value. The cvar is accessed by name.
  *
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the set_pcvar_float function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent set_pcvar_float() function should be used
+ *       instead.
  *
  * @param cvar      Cvar name to set value of
  * @param value     Value to set cvar to
@@ -249,10 +264,9 @@ native set_cvar_float(const cvar[], Float:value);
 /**
  * Returns an integer value from a cvar. The cvar is accessed by name.
  *
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the get_pcvar_num function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent get_pcvar_num() function should be used
+ *       instead.
  *
  * @param cvarname  Cvar name to retrieve value from
  *
@@ -263,10 +277,9 @@ native get_cvar_num(const cvarname[]);
 /**
  * Sets a cvar to a given integer value. The cvar is accessed by name.
  *
- * @note Accessing a Cvar by name requires this function to walk through the
- *       engine's cvar list every time, which can result in a considerable waste
- *       of processing time, especially if many cvars have been registered. For
- *       a vastly superior alternative look at the set_pcvar_num function.
+ * @note Accessing a Cvar by name is slower than direct pointer access, which is
+ *       why the otherwise equivalent set_pcvar_num() function should be used
+ *       instead.
  *
  * @param cvar      Cvar name to set value of
  * @param value     Value to set cvar to
@@ -283,7 +296,8 @@ native set_cvar_num(const cvarname[], value);
  * @param pcvar     Pointer to cvar to retrieve flags from
  *
  * @return          1 on success, 0 if cvar pointer is invalid
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native get_pcvar_flags(pcvar);
 
@@ -298,7 +312,8 @@ native get_pcvar_flags(pcvar);
  * @param flags     Bitflag sum of flags to set
  *
  * @return          1 on success, 0 if cvar does not exist or is not permitted
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native set_pcvar_flags(pcvar, flags);
 
@@ -308,7 +323,8 @@ native set_pcvar_flags(pcvar, flags);
  * @param pcvar     Pointer to cvar to retrieve value from
  *
  * @return          Cvar value, converted to int
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native get_pcvar_num(pcvar);
 
@@ -318,7 +334,8 @@ native get_pcvar_num(pcvar);
  * @param pcvar     Pointer to cvar to retrieve value from
  *
  * @return          Cvar value, converted to bool
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native bool:get_pcvar_bool(pcvar);
 
@@ -329,7 +346,8 @@ native bool:get_pcvar_bool(pcvar);
  * @param num       Value to set cvar to
  *
  * @noreturn
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native set_pcvar_num(pcvar, num);
 
@@ -340,7 +358,8 @@ native set_pcvar_num(pcvar, num);
  * @param num       Value to set cvar to
  *
  * @noreturn
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native set_pcvar_bool(pcvar, bool:num);
 
@@ -350,7 +369,8 @@ native set_pcvar_bool(pcvar, bool:num);
  * @param pcvar     Pointer to cvar to retrieve value from
  *
  * @return          Cvar value, converted to float
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native Float:get_pcvar_float(pcvar);
 
@@ -361,7 +381,8 @@ native Float:get_pcvar_float(pcvar);
  * @param num       Value to set cvar to
  *
  * @noreturn
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native set_pcvar_float(pcvar, Float:num);
 
@@ -373,7 +394,8 @@ native set_pcvar_float(pcvar, Float:num);
  * @param maxlen    Maximum size of the buffer
  *
  * @return          Number of cells written to buffer.
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native get_pcvar_string(pcvar, string[], maxlen);
 
@@ -384,40 +406,36 @@ native get_pcvar_string(pcvar, string[], maxlen);
  * @param string    Value to set cvar to
  *
  * @noreturn
- * @error           If an invalid cvar pointer is specified, an error is thrown.
+ * @error           If an invalid cvar pointer is provided, an error will be
+ *                  thrown.
  */
 native set_pcvar_string(pcvar, const string[]);
 
 /**
- * Cvar bound values used with get/set_pcvar_bounds()
- */
-enum CvarBounds
-{
-    CvarBound_Upper = 0,
-    CvarBound_Lower
-};
-
-/**
- * Retrieves the specified value bounds of a cvar.
+ * Retrieves the specified value boundary of a cvar.
  *
  * @param pcvar     Pointer to cvar
- * @param type      Type of bound to retrieve, CvarBound_Lower or CvarBound_Upper
- * @param value     Variable to store the specified bound to
+ * @param type      Type of boundary to retrieve
+ * @param value     Variable to store the specified boundary to
  *
- * @return          True if the cvar has the specified bound set, false otherwise.
- * @error           If an invalid cvar pointer or CvarBounds value, an error is thrown.
+ * @return          True if the cvar has a boundary set, false otherwise
+ * @error           If an invalid cvar pointer or boundary type is provided,
+ *                  an error will be thrown.
  */
 native bool:get_pcvar_bounds(pcvar, CvarBounds:type, &Float:value);
 
 /**
- * Sets the specified bounds of a cvar.
+ * Sets the specified boundary of a cvar.
  *
  * @param pcvar     Pointer to cvar
- * @param type      Type of bound to set, CvarBound_Lower or CvarBound_Upper
- * @param set       If set to true, cvar will use specified bound. If false, bound will be removed
- * @param value     Floating point value to use as the specified bound
+ * @param type      Type of boundary to set
+ * @param set       If true the cvar boundary will be set, otherwise it will be
+ *                  removed (value is ignored)
+ * @param value     Floating point value to use as the boundary
  *
- * @error           If an invalid cvar pointer or CvarBounds value, an error is thrown.
+ * @noreturn
+ * @error           If an invalid cvar pointer or boundary type is provided, an
+ *                  error will be thrown.
  */
 native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0);
 
@@ -432,7 +450,9 @@ native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0);
  * @param pcvar     Pointer to cvar
  * @param var       Global variable to keep updated
  *
- * @error           Invalid cvar pointer, invalid provided variable or cvar/variable already binded.
+ * @noreturn
+ * @error           If an invalid cvar pointer or variable is provided, an error
+ *                  will be thrown.
  */
 native bind_pcvar_num(pcvar, &any:var);
 
@@ -447,7 +467,9 @@ native bind_pcvar_num(pcvar, &any:var);
  * @param pcvar     Pointer to cvar
  * @param var       Global variable to keep updated
  *
- * @error           Invalid cvar pointer, invalid provided variable or cvar/variable already binded.
+ * @noreturn
+ * @error           If an invalid cvar pointer or variable is provided, an error
+ *                  will be thrown.
  */
 native bind_pcvar_float(pcvar, &Float:var);
 
@@ -463,7 +485,9 @@ native bind_pcvar_float(pcvar, &Float:var);
  * @param var       Global array to keep updated
  * @param varlen    Maximum length of string array
  *
- * @error           Invalid cvar pointer, invalid provided variable or cvar/variable already binded.
+ * @noreturn
+ * @error           If an invalid cvar pointer or variable is provided, an error
+ *                  will be thrown.
  */
 native bind_pcvar_string(pcvar, any:var[], varlen);
 
@@ -475,13 +499,14 @@ native bind_pcvar_string(pcvar, any:var[], varlen);
 native get_plugins_cvarsnum();
 
 /**
- * Retrieves information about a plugin-registered cvar.
+ * Retrieves information about a plugin-registered cvar via iterative access.
  *
  * @note The returned cvar pointer should be used with the get_pcvar_* and
  *       set_pcvar_* set of functions.
+ * @note The cvar index does not equal the cvar pointer. It is the internal
+ *       AMXX id of a cvar, incremented for each registered cvar.
  *
- * @param num           Cvar index, this does not equal the cvar pointer, it is
- *                      the internal index, incremented for each registered cvar
+ * @param num           Index to retrieve
  * @param name          Buffer to copy cvar name to
  * @param namelen       Maximum buffer size
  * @param flags         Variable to store cvar flags to
@@ -492,7 +517,7 @@ native get_plugins_cvarsnum();
  *
  * @return              1 on success, 0 if index is invalid
  */
-native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_handle=0, description[]="", desc_len=0);
+native get_plugins_cvar(num, name[], namelen, &flags = 0, &plugin_id = 0, &pcvar_handle = 0, description[] = "", desc_len = 0);
 
 /**
  * Dispatches a client cvar query, allowing the plugin to query for its value on
@@ -502,10 +527,10 @@ native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_han
  *
  * public cvar_query_callback(id, const cvar[], const value[], const param[])
  *
- *  id      - Client index
- *  cvar    - Cvar queried
- *  value   - Cvar value on the client
- *  param   - Extra data [optional]
+ *   id      - Client index
+ *   cvar    - Cvar queried
+ *   value   - Cvar value on the client
+ *   param   - Optional extra data
  *
  * @param id            Client index
  * @param cvar          Cvar to query
@@ -515,10 +540,8 @@ native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_han
  *
  * @noreturn
  * @error               If the client index is not within the range of 1 to
- *                      MaxClients or the client is not connected, an error
- *                      will be thrown.
- *                      If the callback function is invalid, cvar querying is
- *                      unavailable or the querying process runs out of memory,
- *                      an error will be thrown.
+ *                      MaxClients, the client is not connected, the callback
+ *                      function is invalid or the querying process encounters
+ *                      a problem, an error will be thrown.
  */
-native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[]="");
+native query_client_cvar(id, const cvar[], const resultFunc[], paramlen = 0, const params[] = "");

From 950f3f97c1d4c72e5d5961d399df4a59f43f2303 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 24 Feb 2015 22:16:36 +0100
Subject: [PATCH 07/10] datapack: Tabs->spaces, consistency, nuke
 IsPackReadable

---
 plugins/include/datapack.inc | 138 +++++++++++++++++++----------------
 1 file changed, 76 insertions(+), 62 deletions(-)

diff --git a/plugins/include/datapack.inc b/plugins/include/datapack.inc
index 80d12648..27950db5 100644
--- a/plugins/include/datapack.inc
+++ b/plugins/include/datapack.inc
@@ -8,131 +8,145 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _datapack_included
-	#endinput
+    #endinput
 #endif
-#define _datapack_included	
+#define _datapack_included
 
 /**
- * DataPacks are a way to store and move around various types of data in AMX Mod X Scripting. 
- * Since some things are not possible in AMX Mod X, such as a function consuming a String, 
- * DataPacks help us get these Strings and other items where they need to go.
+ * Datapack tag declaration
+ *
+ * @note Datapacks provide a way to store and move around arbitrary amounts (and
+ *       types) of data in AMX Mox X. Data is packed into a single cell value -
+ *       the DataPack handle. This handle can be passed around more easily, can
+ *       be returned by functions and can simulate advanced concepts like string
+ *       consummation.
+ * @note Plugins are responsible for freeing all datapack handles they acquire.
+ *       Failing to free handles will result in the plugin and AMXX leaking
+ *       memory.
  */
 
 enum DataPack
 {
-	Invalid_DataPack = 0
+    Invalid_DataPack = 0
 };
 
 /**
- * Creates a new data pack.
+ * Creates a new datapack.
  *
- * @return			A Handle to the data pack.
+ * @return  New datapack handle, which must be freed via DestroyDataPack().
  */
 native DataPack:CreateDataPack();
 
 /**
- * Packs a normal cell into a data pack.
+ * Packs a cell value into a datapack.
+ *
+ * @param pack      Datapack handle
+ * @param cell      Cell value to pack
  *
- * @param pack		Handle to the data pack.
- * @param cell		Cell to add.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackCell(DataPack:pack, any:cell);
 
 /**
- * Packs a float into a data pack.
+ * Packs a float value into a datapack.
+ *
+ * @param pack      Datapack handle
+ * @param val       Float value to pack
  *
- * @param pack		Handle to the data pack.
- * @param val		Float to add.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackFloat(DataPack:pack, Float:val);
 
 /**
- * Packs a string into a data pack.
+ * Packs a string into a datapack.
  *
- * @param pack		Handle to the data pack.
- * @param str		String to add.
- * @return			Length of copied string.
- * @error			Invalid handle.
+ * @param pack      Datapack handle
+ * @param str       String to pack
+ *
+ * @return          Length of copied string
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackString(DataPack:pack, const str[]);
 
 /**
- * Reads a cell from a data pack.
+ * Reads a cell from a Datapack.
  *
- * @param pack		Handle to the data pack.
- * @return			Cell value.
- * @error			Invalid handle, or bounds error.
+ * @param pack      Datapack handle
+ *
+ * @return          Cell value
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
 native any:ReadPackCell(DataPack:pack);
 
 /**
- * Reads a float from a data pack.
+ * Reads a float from a datapack.
  *
- * @param pack		Handle to the data pack.
- * @return			Float value.
- * @error			Invalid handle, or bounds error.
+ * @param pack      Datapack handle
+ *
+ * @return          Float value
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
-native Float:ReadPackFloat(DataPack:pack);
+native Float:ReadPackFloat(datapack:pack);
 
 /**
- * Reads a string from a data pack.
+ * Reads a string from a Datapack.
  *
- * @param pack		Handle to the data pack.
- * @param buffer	Destination string buffer.
- * @param maxlen	Maximum length of output string buffer.
- * @return			Length of output string.
- * @error			Invalid handle, or bounds error.
+ * @param pack      Datapack handle
+ * @param buffer    Buffer to copy string to
+ * @param maxlen    Maximum size of buffer
+ *
+ * @return          Number of cells written to buffer
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
 native ReadPackString(DataPack:pack, buffer[], maxlen);
 
 /**
- * Resets the position in a data pack.
+ * Resets the datapack read/write position to the start.
+ *
+ * @param pack      Datapack handle
+ * @param clear     If true, clears the contained data
  *
- * @param pack		Handle to the data pack.
- * @param clear		If true, clears the contained data.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
-native ResetPack(DataPack:pack, bool:clear=false);
+native ResetPack(DataPack:pack, bool:clear = false);
 
 /**
- * Returns the read or write position in a data pack.
+ * Returns the datapack read/write position.
  *
- * @param pack		Handle to the data pack.
- * @return			Numerical position in the data pack.
- * @error			Invalid handle.
+ * @param pack      Datapack handle
+ *
+ * @return          Position in the datapack
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native GetPackPosition(DataPack:pack);
 
 /**
- * Sets the read/write position in a data pack.
+ * Sets the datapack read/write position.
+ *
+ * @note This should only ever be used with (known to be valid) positions
+ *       returned by GetPackPosition(). It is not possible for plugins to safely
+ *       compute datapack positions.
+ *
+ * @param pack      Datapack handle
+ * @param position  New position to set
  *
- * @param pack		Handle to the data pack.
- * @param position	New position to set.
  * @noreturn
- * @error			Invalid handle, or position is beyond the pack bounds.
+ * @error           If an invalid handle is provided, or the new position is
+ *                  out of datapack bounds, an error will be thrown.
  */
 native SetPackPosition(DataPack:pack, position);
 
 /**
- * Returns whether or not a specified number of bytes from the data pack
- *  position to the end can be read.
+ * Destroys the datapack and frees its memory.
  *
- * @param pack		Handle to the data pack.
- * @param bytes		Number of bytes to simulate reading.
- * @return			True if can be read, false otherwise.
- * @error			Invalid handle.
- */
-native bool:IsPackReadable(DataPack:pack, bytes);
-
-/**
- * Disposes of a data pack.
+ * @param pack      Datapack handle
  *
- * @param pack		Handle to the data pack.
- * @return			True if disposed, false otherwise.
+ * @return          True if disposed, false otherwise
  */
 native DestroyDataPack(&DataPack:pack);

From 902cecb0c3611ded2214db9962edf52cf209f97a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 24 Feb 2015 22:20:46 +0100
Subject: [PATCH 08/10] amxconst: Minor improvements on client_print natives

---
 plugins/include/amxmodx.inc | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc
index fe8d9988..1b1b0f56 100755
--- a/plugins/include/amxmodx.inc
+++ b/plugins/include/amxmodx.inc
@@ -339,7 +339,8 @@ native show_motd(player, const message[], const header[] = "");
  *       last, to the client with the highest index.
  *
  * @param index     Client index, use 0 to display to all clients
- * @param type      Message type, see print_* destination constants in amxconst
+ * @param type      Message type, see print_* destination constants in
+ *                  amxconst.inc
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
@@ -361,8 +362,9 @@ native client_print(index, type, const message[], any:...);
  *                                ; This only works at the start of the string,
  *                                ; and precludes using other control characters
  *          default         x01   ; use default color from this point forward
- * @note The team color is defined by the sender's index or a specific team
- *       color using the print_team_* constants in amxconst
+ * @note The team color is defined by the sender's index. Alternatively a
+ *       specific team color can be enforced using the print_team_* constants in
+ *       amxconst.inc
  * @note Usage examples:
  *       client_print_color(id, print_team_red, "^4Green ^3Red ^1Default")
  *       client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default")
@@ -376,9 +378,7 @@ native client_print(index, type, const message[], any:...);
  *       last, to the client with the highest index.
  *
  * @param index     Client index, use 0 to display to all clients
- * @param sender    Client index used as the sender, defining the team color
- *                  used in the message. Use print_team_* constants to force
- *                  a specific color.
+ * @param sender    Client index used as the message sender
  * @param fmt       Formatting rules
  * @param ...       Variable number of formatting parameters
  *
@@ -399,7 +399,8 @@ native client_print_color(index, sender, const message[], any:...);
  *       last, to the client with the highest index.
  *
  * @param player    Client index, use 0 to display to all clients
- * @param type      Message type, see print_* destination constants in amxconst
+ * @param type      Message type, see print_* destination constants in
+ *                  amxconst.inc
  * @param message   Formatting rules
  * @param ...       Variable number of formatting parameters
  *

From bc9710e8f22da1ce68790b7362f3656f3ed890c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= <nextra.24@gmail.com>
Date: Tue, 24 Feb 2015 22:51:36 +0100
Subject: [PATCH 09/10] inc-doc2 nits/finishing touches

---
 plugins/include/amxconst.inc        |  2 +-
 plugins/include/amxmisc.inc         |  2 +-
 plugins/include/amxmodx.inc         | 19 +++----
 plugins/include/amxmodx_version.inc |  2 +-
 plugins/include/celltrie.inc        |  2 +-
 plugins/include/core.inc            |  4 +-
 plugins/include/csstats.inc         | 10 ++--
 plugins/include/cstrike.inc         | 80 ++++++++++++++---------------
 plugins/include/csx.inc             | 16 +++---
 plugins/include/cvars.inc           |  8 +--
 plugins/include/datapack.inc        |  5 +-
 11 files changed, 73 insertions(+), 77 deletions(-)

diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc
index 84d61b02..72d1fa95 100755
--- a/plugins/include/amxconst.inc
+++ b/plugins/include/amxconst.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _amxconst_included
-  #endinput
+	#endinput
 #endif
 #define _amxconst_included
 
diff --git a/plugins/include/amxmisc.inc b/plugins/include/amxmisc.inc
index 8c516f0b..448293e9 100755
--- a/plugins/include/amxmisc.inc
+++ b/plugins/include/amxmisc.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _amxmisc_included
-  #endinput
+	#endinput
 #endif
 #define _amxmisc_included
 
diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc
index 1b1b0f56..099dc984 100755
--- a/plugins/include/amxmodx.inc
+++ b/plugins/include/amxmodx.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _amxmodx_included
-  #endinput
+	#endinput
 #endif
 #define _amxmodx_included
 
@@ -100,8 +100,8 @@ forward plugin_end();
 /**
  * Called when a message is about to be logged.
  *
- * @note Message data and information can be retrieved using the read_log set of
- *       functions.
+ * @note Message data and information can be retrieved using the read_log* set
+ * 		 of functions.
  *
  * @return      PLUGIN_CONTINUE to let the log message through
  *              PLUGIN_HANDLED or higher to stop the log message
@@ -687,40 +687,34 @@ native read_datatype();
 /**
  * Retrieves current log message.
  *
- * @note Can only be used inside of the plugin_log() forward.
+ * @note Should only be used inside of the plugin_log() forward.
  *
  * @param output    Buffer to copy log message to
  * @param len       Maximum buffer size
  *
  * @return          Number of cells written to buffer
- * @error           If called outside of the plugin_log() forward, an error is
- *                  thrown.
  */
 native read_logdata(output[], len);
 
 /**
  * Returns number of log message arguments.
  *
- * @note Can only be used inside of the plugin_log() forward.
+ * @note Should only be used inside of the plugin_log() forward.
  *
  * @return          Number of arguments in the log message
- * @error           If called outside of the plugin_log() forward, an error is
- *                  thrown.
  */
 native read_logargc();
 
 /**
  * Retrieves argument of log message.
  *
- * @note Can only be used inside of the plugin_log() forward.
+ * @note Should only be used inside of the plugin_log() forward.
  *
  * @param id        Argument index, starting from 0
  * @param output    Buffer to copy log argument to
  * @param len       Maximum buffer size
  *
  * @return          Number of cells written to buffer
- * @error           If called outside of the plugin_log() forward, an error is
- *                  thrown.
  */
 native read_logargv(id, output[], len);
 
@@ -871,7 +865,6 @@ native get_amxx_verstring(buffer[], length);
  * @error           If the client index is not within the range of 1 to
  *                  MaxClients an error will be thrown.
  */
-
 native get_user_attacker(index, ...);
 
 /**
diff --git a/plugins/include/amxmodx_version.inc b/plugins/include/amxmodx_version.inc
index faba7062..7d9c502a 100644
--- a/plugins/include/amxmodx_version.inc
+++ b/plugins/include/amxmodx_version.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _amxmodx_version_included
-  #endinput
+	#endinput
 #endif
 #define _amxmodx_version_included
 
diff --git a/plugins/include/celltrie.inc b/plugins/include/celltrie.inc
index 729be00c..bcf0b757 100644
--- a/plugins/include/celltrie.inc
+++ b/plugins/include/celltrie.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _celltrie_included
-    #endinput
+	#endinput
 #endif
 #define _celltrie_included
 
diff --git a/plugins/include/core.inc b/plugins/include/core.inc
index 7b8ba5f9..93626ca1 100755
--- a/plugins/include/core.inc
+++ b/plugins/include/core.inc
@@ -6,7 +6,7 @@
 */
 
 #if defined _core_included
-  #endinput
+	#endinput
 #endif
 #define _core_included
 
@@ -198,5 +198,5 @@ native tickcount(&granularity = 0);
  */
 stock abs(x)
 {
-    return x > 0 ? x : -x;
+	return x > 0 ? x : -x;
 }
diff --git a/plugins/include/csstats.inc b/plugins/include/csstats.inc
index 9bb7c099..96e168ef 100755
--- a/plugins/include/csstats.inc
+++ b/plugins/include/csstats.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _csstats_included
-  #endinput
+	#endinput
 #endif
 #define _csstats_included
 
@@ -75,7 +75,9 @@ native get_user_wrstats(index, wpnindex, stats[8], bodyhits[8]);
  * server.
  *
  * @note The permanent storage is updated on every respawn or client disconnect.
- * @note Player rank is determined by the difference of kills to deaths.
+ * @note Player rank is determined by the customizable "get_score" function in
+ *       "data/csstats.amxx". By default it uses the difference of kills to
+ *       deaths/teamkills.
  * @note For a list of possible body hitplaces see the HIT_* constants in
  *       amxconst.inc
  * @note The fields in the statistics are:
@@ -199,7 +201,9 @@ native reset_user_wstats(index);
  * incremental access.
  *
  * @note The permanent storage is updated on every respawn or client disconnect.
- * @note Player rank is determined by the difference of kills to deaths.
+ * @note Player rank is determined by the customizable "get_score" function in
+ *       "data/csstats.amxx". By default it uses the difference of kills to
+ *       deaths/teamkills.
  * @note For a list of possible body hitplaces see the HIT_* constants in
  *       amxconst.inc
  * @note The fields in the statistics are:
diff --git a/plugins/include/cstrike.inc b/plugins/include/cstrike.inc
index 2ee0752d..764742cd 100755
--- a/plugins/include/cstrike.inc
+++ b/plugins/include/cstrike.inc
@@ -12,7 +12,7 @@
 //
 
 #if defined _cstrike_included
- #endinput
+	#endinput
 #endif
 #define _cstrike_included
 
@@ -36,18 +36,18 @@
  */
 enum CsInternalModel
 {
-    CS_DONTCHANGE = 0,
-    CS_CT_URBAN = 1,
-    CS_T_TERROR = 2,
-    CS_T_LEET = 3,
-    CS_T_ARCTIC = 4,
-    CS_CT_GSG9 = 5,
-    CS_CT_GIGN = 6,
-    CS_CT_SAS = 7,
-    CS_T_GUERILLA = 8,
-    CS_CT_VIP = 9,
-    CZ_T_MILITIA = 10,
-    CZ_CT_SPETSNAZ = 11,
+	CS_DONTCHANGE = 0,
+	CS_CT_URBAN = 1,
+	CS_T_TERROR = 2,
+	CS_T_LEET = 3,
+	CS_T_ARCTIC = 4,
+	CS_CT_GSG9 = 5,
+	CS_CT_GIGN = 6,
+	CS_CT_SAS = 7,
+	CS_T_GUERILLA = 8,
+	CS_CT_VIP = 9,
+	CZ_T_MILITIA = 10,
+	CZ_CT_SPETSNAZ = 11,
 };
 
 /**
@@ -55,10 +55,10 @@ enum CsInternalModel
  */
 enum CsTeams
 {
-    CS_TEAM_UNASSIGNED = 0,
-    CS_TEAM_T = 1,
-    CS_TEAM_CT = 2,
-    CS_TEAM_SPECTATOR = 3,
+	CS_TEAM_UNASSIGNED = 0,
+	CS_TEAM_T = 1,
+	CS_TEAM_CT = 2,
+	CS_TEAM_SPECTATOR = 3,
 };
 
 /**
@@ -70,9 +70,9 @@ enum CsTeams
  */
 enum CsArmorType
 {
-    CS_ARMOR_NONE = 0,      // no armor
-    CS_ARMOR_KEVLAR = 1,    // body vest only
-    CS_ARMOR_VESTHELM = 2,  // vest and helmet
+	CS_ARMOR_NONE = 0,      // no armor
+	CS_ARMOR_KEVLAR = 1,    // body vest only
+	CS_ARMOR_VESTHELM = 2,  // vest and helmet
 };
 
 /**
@@ -89,11 +89,11 @@ enum CsArmorType
  */
 enum
 {
-    CS_RESET_ZOOM = 0,      // Reset any zoom blocking (mode has no effect)
-    CS_SET_NO_ZOOM,         // Disable any sort of zoom
-    CS_SET_FIRST_ZOOM,      // Set first zoom level (AWP style)
-    CS_SET_SECOND_ZOOM,     // Set second zoom level (AWP style)
-    CS_SET_AUGSG552_ZOOM,   // Set AUG/SG552 zoom style
+	CS_RESET_ZOOM = 0,      // Reset any zoom blocking (mode has no effect)
+	CS_SET_NO_ZOOM,         // Disable any sort of zoom
+	CS_SET_FIRST_ZOOM,      // Set first zoom level (AWP style)
+	CS_SET_SECOND_ZOOM,     // Set second zoom level (AWP style)
+	CS_SET_AUGSG552_ZOOM,   // Set AUG/SG552 zoom style
 };
 
 /**
@@ -246,19 +246,19 @@ native cs_get_user_bpammo(index, weapon);
  *       amxconst.inc
  * @note Some weapons share ammo types and therefore ammo backpack pools. List
  *       of ammo types:
- *       awp - ammo_338magnum
- *       scout, ak47, g3sg1 - ammo_762nato
- *       m249 - ammo_556natobox
- *       famas, m4a1, aug, sg550, galil, sg552 - ammo_556nato
- *       m3, xm1014 - ammo_buckshot
- *       usp, ump45, mac10 - ammo_45acp
- *       fiveseven, p90 - ammo_57mm
- *       deagle - ammo_50ae
- *       p228 - ammo_357sig
- *       glock, mp5, tmp, elites - ammo_9mm
- *       hegrenade - /
- *       flashbang - /
- *       smokegrenade - /
+ *       ammo_338magnum  - awp
+ *       ammo_762nato    - scout, ak47, g3sg1
+ *       ammo_556natobox - m249
+ *       ammo_556nato    - famas, m4a1, aug, sg550, galil, sg552
+ *       ammo_buckshot   - m3, xm1014
+ *       ammo_45acp      - usp, ump45, mac10
+ *       ammo_57mm       - fiveseven, p90
+ *       ammo_50ae       - deagle
+ *       ammo_357sig     - p228
+ *       ammo_9mm        - glock, mp5, tmp, elites
+ *       /               - hegrenade
+ *       /               - flashbang
+ *       /               - smokegrenade
  *
  * @param index     Client index
  * @param weapon    Weapon id
@@ -1061,7 +1061,7 @@ native cs_set_c4_explode_time(index, Float:value);
 /**
  * Returns if the bomb is being defused.
  *
- * @param index     C4 entity
+ * @param c4index   C4 entity
  *
  * @return          1 if the bomb is being defused, 0 otherwise
  * @error           If the provided entity index is not a bomb, an error will be
@@ -1072,7 +1072,7 @@ native bool:cs_get_c4_defusing(c4index);
 /**
  * Sets if the bomb is being defused.
  *
- * @param index     C4 entity
+ * @param c4index   C4 entity
  * @param defusing  True if the bomb should be defused, false otherwise
  *
  * @noreturn
diff --git a/plugins/include/csx.inc b/plugins/include/csx.inc
index 70d90883..c05304ea 100755
--- a/plugins/include/csx.inc
+++ b/plugins/include/csx.inc
@@ -12,7 +12,7 @@
 //
 
 #if defined _csx_included
-  #endinput
+	#endinput
 #endif
 #define _csx_included
 
@@ -32,10 +32,10 @@
  */
 enum MapObjective
 {
-    MapObjective_Bomb    = (1<<0),
-    MapObjective_Hostage = (1<<1),
-    MapObjective_Vip     = (1<<2),
-    MapObjective_Escape  = (1<<3),
+	MapObjective_Bomb    = (1<<0),
+	MapObjective_Hostage = (1<<1),
+	MapObjective_Vip     = (1<<2),
+	MapObjective_Escape  = (1<<3),
 };
 
 /**
@@ -154,7 +154,7 @@ forward bomb_defused(defuser);
 native custom_weapon_add(const wpnname[], melee = 0, const logname[] = "");
 
 /**
- * Trigger a damage event on a custom weapon, adding it to the internal stats.
+ * Triggers a damage event on a custom weapon, adding it to the internal stats.
  *
  * @note This will also call the client_damage() and client_kill() forwards if
  *       applicable.
@@ -175,7 +175,7 @@ native custom_weapon_add(const wpnname[], melee = 0, const logname[] = "");
 native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0);
 
 /**
- * Add a shot event on a custom weapon to the internal stats.
+ * Adds a shot event on a custom weapon to the internal stats.
  *
  * @param weapon    Custom weapon id
  * @param index     Client index
@@ -184,7 +184,7 @@ native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0);
  * @error           If the weapon id is not a custom weapon or an invalid client
  *                  index is provided, an error will be thrown.
  */
-native custom_weapon_shot(weapon, index); // weapon id , player id
+native custom_weapon_shot(weapon, index);
 
 /**
  * Returns if the weapon is considered a melee weapon.
diff --git a/plugins/include/cvars.inc b/plugins/include/cvars.inc
index 38cca88c..2e86f9ae 100644
--- a/plugins/include/cvars.inc
+++ b/plugins/include/cvars.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _cvars_included
-    #endinput
+	#endinput
 #endif
 #define _cvars_included
 
@@ -32,8 +32,8 @@
  */
 enum CvarBounds
 {
-    CvarBound_Upper = 0,
-    CvarBound_Lower
+	CvarBound_Upper = 0,
+	CvarBound_Lower
 };
 
 /**
@@ -156,7 +156,7 @@ native disable_cvar_hook(cvarhook:handle);
 native enable_cvar_hook(cvarhook:handle);
 
 /**
- * Returns a flags of a cvar. The cvar is accessed by name.
+ * Returns flags of a cvar. The cvar is accessed by name.
  *
  * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
  * @note Accessing a Cvar by name is slower than direct pointer access, which is
diff --git a/plugins/include/datapack.inc b/plugins/include/datapack.inc
index 27950db5..fd2743b3 100644
--- a/plugins/include/datapack.inc
+++ b/plugins/include/datapack.inc
@@ -8,7 +8,7 @@
 //     https://alliedmods.net/amxmodx-license
 
 #if defined _datapack_included
-    #endinput
+	#endinput
 #endif
 #define _datapack_included
 
@@ -24,10 +24,9 @@
  *       Failing to free handles will result in the plugin and AMXX leaking
  *       memory.
  */
-
 enum DataPack
 {
-    Invalid_DataPack = 0
+	Invalid_DataPack = 0
 };
 
 /**

From a82f5216333dcb5711639f9926136a0f63af57f8 Mon Sep 17 00:00:00 2001
From: Freeman-AM <luc.marle@laposte.net>
Date: Sun, 1 Mar 2015 16:42:32 +0100
Subject: [PATCH 10/10] amxmodx.inc: missing commas, typo errors...

---
 plugins/include/amxmodx.inc | 378 ++++++++++++++++++------------------
 1 file changed, 186 insertions(+), 192 deletions(-)

diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc
index 099dc984..ca469d4f 100755
--- a/plugins/include/amxmodx.inc
+++ b/plugins/include/amxmodx.inc
@@ -35,8 +35,8 @@
  * Called just after server activation.
  *
  * @note Good place to initialize most of the plugin, such as registering
- *       cvars, commands or forwards, creating data structures for later use or
- *       generating and loading other required configuration.
+ *       cvars, commands or forwards, creating data structures for later use, or
+ *       generating and loading other required configurations.
  *
  * @noreturn
  */
@@ -49,7 +49,6 @@ forward plugin_init();
  */
 forward plugin_pause();
 
-
 /**
  * Called just after the plugin is unpaused.
  *
@@ -61,11 +60,11 @@ forward plugin_unpause();
  * Called when the mod tries to change the map.
  *
  * @note This is *only* called if the mod itself handles the map change. The
- *       server command "changelevel" which is used by many plugins will not
- *       trigger this forward. Unfortunately this means that in practice this
- *       forward is very unreliable, and will not be called in many situations.
- * @note AMXX 1.8.3 has added the engine_changelevel() function which will utilize
- *       the correct engine function to change the map and therefore trigger
+ *       server command "changelevel", which is used by many plugins, will not
+ *       trigger this forward. Unfortunately, this means that in practice this
+ *       forward can be unreliable and will not be called in many situations.
+ * @note AMXX 1.8.3 has added the engine_changelevel() function, which will utilize
+ *       the correct engine function to change the map, and therefore trigger
  *       this forward.
  *
  * @param map   Map that the mod tries to change to
@@ -76,9 +75,9 @@ forward plugin_unpause();
 forward server_changelevel(map[]);
 
 /**
- * Called when all plugins went through plugin_init().
+ * Called when all plugins went through plugin_init()
  *
- * @note When this forward is called most plugins should have registered their
+ * @note When this forward is called, most plugins should have registered their
  *       cvars and commands already.
  *
  * @noreturn
@@ -101,7 +100,7 @@ forward plugin_end();
  * Called when a message is about to be logged.
  *
  * @note Message data and information can be retrieved using the read_log* set
- * 		 of functions.
+ *       of functions.
  *
  * @return      PLUGIN_CONTINUE to let the log message through
  *              PLUGIN_HANDLED or higher to stop the log message
@@ -225,8 +224,7 @@ native precache_model(const name[]);
  *       to be a wav file. Precaching a file with this will add it to the engine
  *       sound table, making it available for usage in emit_sound() for example.
  * @note Precaching other filetypes (such as mp3 music), optionally in different
- *       locations, has to be done with precache_generic.
- *
+ *       locations, has to be done with precache_generic()
  *
  * @param name  Path to the sound file
  *
@@ -240,7 +238,7 @@ native precache_sound(const name[]);
  * Precaches a generic file.
  *
  * @note Can only be used inside of the plugin_precache() forward.
- * @note Precaching sounds with this will not add them to the engine sound table
+ * @note Precaching sounds with this will not add them to the engine sound table.
  *
  * @param szFile    Path to the file
  *
@@ -274,7 +272,7 @@ native engine_changelevel(const map[]);
  *
  * @noreturn
  * @error           If the index is not within the range of 1 to MaxClients or
- *                  the client is not connected an error will be thrown.
+ *                  the client is not connected, an error will be thrown.
  * @error           If called outside of the plugin_precache() forward, an error
  *                  is thrown.
  */
@@ -290,7 +288,7 @@ native set_user_info(index, const info[], const value[]);
  *
  * @return          Number of cells written to buffer
  * @error           If the index is not within the range of 1 to MaxClients or
- *                  the client is not connected an error will be thrown.
+ *                  the client is not connected, an error will be thrown.
  */
 native get_user_info(index, const info[], output[], len);
 
@@ -345,8 +343,8 @@ native show_motd(player, const message[], const header[] = "");
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native client_print(index, type, const message[], any:...);
 
@@ -362,18 +360,18 @@ native client_print(index, type, const message[], any:...);
  *                                ; This only works at the start of the string,
  *                                ; and precludes using other control characters
  *          default         x01   ; use default color from this point forward
- * @note The team color is defined by the sender's index. Alternatively a
+ * @note The team color is defined by the sender's index. Alternatively, a
  *       specific team color can be enforced using the print_team_* constants in
  *       amxconst.inc
  * @note Usage examples:
  *       client_print_color(id, print_team_red, "^4Green ^3Red ^1Default")
  *       client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default")
  * @note Including colors in ML can be done using the same escaping method:
- *       EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default.
+ *       EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default
  * @note This functions return value behaves differently depending on what is
  *       used as the client index: If 0 is specified, then the function will
  *       return 0 if nothing has been sent (no client connected). If either a
- *       single client is specified or there is at least one client connected,
+ *       single client is specified, or there is at least one client connected,
  *       the number of printed characters will refer to the message that is sent
  *       last, to the client with the highest index.
  *
@@ -383,8 +381,8 @@ native client_print(index, type, const message[], any:...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native client_print_color(index, sender, const message[], any:...);
 
@@ -394,7 +392,7 @@ native client_print_color(index, sender, const message[], any:...);
  * @note This functions return value behaves differently depending on what is
  *       used as the client index: If 0 is specified, then the function will
  *       return 0 if nothing has been sent (no client connected). If either a
- *       single client is specified or there is at least one client connected,
+ *       single client is specified, or there is at least one client connected,
  *       the number of printed characters will refer to the message that is sent
  *       last, to the client with the highest index.
  *
@@ -405,8 +403,8 @@ native client_print_color(index, sender, const message[], any:...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native engclient_print(player, type, const message[], any:...);
 
@@ -418,15 +416,15 @@ native engclient_print(player, type, const message[], any:...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native console_print(id, const message[], any:...);
 
 /**
  * Executes a command from the specified client or the server console.
  *
- * @param id    Client index, or 0 to print to the server console
+ * @param id    Client index, or 0 to execute from the server console
  * @param cmd   Formatting rules
  * @param ...   Variable number of formatting parameters
  *
@@ -512,8 +510,8 @@ native register_logevent(const function[], argsnum, ...);
  * @note There are four different HUD channels available on the client (1-4).
  *       Sending a hudmessage to a channel will overwrite any existing messages
  *       already displaying on that channel.
- * @note If you plan to create a permanent message don't forget to specify a
- *       specific channel to avoid possible flickering due to auto-channeling
+ * @note If you plan to create a permanent message, don't forget to specify a
+ *       specific channel to avoid possible flickering due to auto-channeling.
  * @note For the hudmessage coordinates x and y, -1.0 will center the message
  *       on the respective axis.
  * @note These parameters stay until the next call to set_hudmessage overwrites
@@ -544,7 +542,7 @@ native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y
  * @note This functions return value behaves differently depending on what is
  *       used as the client index: If 0 is specified, then the function will
  *       return 0 if nothing has been sent (no client connected). If either a
- *       single client is specified or there is at least one client connected,
+ *       single client is specified, or there is at least one client connected,
  *       the number of printed characters will refer to the message that is sent
  *       last, to the client with the highest index.
  *
@@ -553,8 +551,8 @@ native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native show_hudmessage(index, const message[], any:...);
 
@@ -587,16 +585,16 @@ native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y
  * Displays a director message on the client HUD.
  *
  * @note Use set_dhudmessage to define how the message should look on screen.
- * @note Unlike the classic HUD message which is channel-based, director
+ * @note Unlike the classic HUD message, which is channel-based, director
  *       messages are stack-based. You can have up to 8 messages displaying at
- *       once, if more are added they will be overwritten in the order they were
+ *       once. If more are added, they will be overwritten in the order they were
  *       sent. There is no way to clear a specific message.
  * @note The message has a maximum length of 128 characters which this function
  *       will automatically enforce.
  * @note This functions return value behaves differently depending on what is
  *       used as the client index: If 0 is specified, then the function will
  *       return 0 if nothing has been sent (no client connected). If either a
- *       single client is specified or there is at least one client connected,
+ *       single client is specified, or there is at least one client connected,
  *       the number of printed characters will refer to the message that is sent
  *       last, to the client with the highest index.
  *
@@ -605,8 +603,8 @@ native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native show_dhudmessage(index, const message[], any:...);
 
@@ -614,16 +612,13 @@ native show_dhudmessage(index, const message[], any:...);
  * Displays a menu to the client.
  *
  * @note Keys is a bitflag value that represents which keys the user can press
- *       on the menu. If you want to display disabled menu options or skip
- *       certain number slots you should exclude that key from the bitflag.
+ *       on the menu. If you want to display disabled menu options, or skip
+ *       certain number slots, you should exclude that key from the bitflag.
  *       amxconst.inc provides MENU_KEY_* constants for convenience.
- * @note If a menu timeout is specified it does not automatically overwrite
- *       the menu on the client's screen. But if a client acts upon a timeouted
- *       displayed menu that action will not be sent to the plugin.
  * @note The title parameter is not displayed to the client and is only used for
  *       identifying menus internally and assigning them to their callbacks.
  *       The title corresponds to the menu name that you register with
- *       register_menuid().
+ *       register_menuid()
  *
  * @param index     Client to display menu to, use 0 to display to all clients
  * @param keys      Enabled keys
@@ -633,15 +628,15 @@ native show_dhudmessage(index, const message[], any:...);
  *
  * @return          1 on success, 0 if menu could not be displayed (client not
  *                  connected)
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native show_menu(index, keys, const menu[], time = -1, const title[] = "");
 
 /**
  * Retrieves values from a client message.
  *
- * @note For use within callbacks registered with register_event().
+ * @note For use within callbacks registered with register_event()
  * @note Usage examples:
  *       value = read_data(1);
  *       read_data(2, floatvalue);
@@ -669,7 +664,7 @@ native read_data(value, any:...);
 /**
  * Returns the number of values in the client message.
  *
- * @note For use within callbacks registered with register_event().
+ * @note For use within callbacks registered with register_event()
  *
  * @return      Number of values in client message
  */
@@ -678,7 +673,7 @@ native read_datanum();
 /**
  * Returns the message id of the client message.
  *
- * @note For use within callbacks registered with register_event().
+ * @note For use within callbacks registered with register_event()
  *
  * @return      Message id of the client message
  */
@@ -721,7 +716,7 @@ native read_logargv(id, output[], len);
 /**
  * Parse log data about client.
  *
- * @note When client actions are logged they appear in the the format
+ * @note When client actions are logged, they appear in the the format
  *       "Name<#userid><SteamID><teamname>", this native extracts the individual
  *       pieces of information.
  *
@@ -856,14 +851,14 @@ native get_amxx_verstring(buffer[], length);
  *       was attacked by a non-client entity.
  *
  * @param index     Client index
- * @param ...       If provided the attacker weapon will be stored in an
+ * @param ...       If provided, the attacker weapon will be stored in an
  *                  optional second parameter, and the body hit place will be
  *                  stored in an optional third parameter
  *
  * @return          Attacker client index, a non-client entity or 0 if no
  *                  attacker was found
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients an error will be thrown.
+ *                  MaxClients, an error will be thrown.
  */
 native get_user_attacker(index, ...);
 
@@ -871,7 +866,7 @@ native get_user_attacker(index, ...);
  * Traces the client's current aim vector to see if it hits something.
  *
  * @note If the trace does not hit a client, id and body will be set to 0.
- * @note If the trace hits nothing within the specified distance 0 is returned.
+ * @note If the trace hits nothing within the specified distance, 0 is returned.
  *
  * @param index     Client index to trace aim from
  * @param id        Variable to store hit client index (if applicable)
@@ -880,14 +875,14 @@ native get_user_attacker(index, ...);
  *
  * @return          Distance between the trace start and end point
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients an error will be thrown.
+ *                  MaxClients, an error will be thrown.
  */
 native Float:get_user_aiming(index, &id, &body, dist = 9999);
 
 /**
  * Returns the client's frags.
  *
- * @note While this is mod-independent the mod may track frag count differently
+ * @note While this is mod-independent, the mod may track frag count differently,
  *       so it can only be retrieved using another native or other methods.
  * @note This will actually return the client's overall score, which may or may
  *       not be equal to their scored frags depending on the mod.
@@ -903,7 +898,7 @@ native get_user_frags(index);
 /**
  * Returns the client's armor value.
  *
- * @note While this is mod-independent the mod may track armor data differently
+ * @note While this is mod-independent, the mod may track armor data differently,
  *       so it can only be retrieved using another native or other methods.
  *
  * @param index     Client index
@@ -917,7 +912,7 @@ native get_user_armor(index);
 /**
  * Returns the client's death count.
  *
- * @note While this is mod-independent the mod may track death count differently
+ * @note While this is mod-independent, the mod may track death count differently,
  *       so it can only be retrieved using another native or other methods.
  *
  * @param index     Client index
@@ -931,8 +926,8 @@ native get_user_deaths(index);
 /**
  * Returns the client's health points.
  *
- * @note While this is mod-independent the mod may track health points
- *       differently so it can only be retrieved using another native or other
+ * @note While this is mod-independent, the mod may track health points
+ *       differently, so it can only be retrieved using another native or other
  *       methods.
  *
  * @param index     Client index
@@ -974,7 +969,7 @@ native get_user_ip(index, ip[], len, without_port = 0);
  *
  * @return              1 if the weapon is present, 0 if it is not
  * @error               If the client index is not within the range of 1 to
- *                      MaxClients an error will be thrown.
+ *                      MaxClients, an error will be thrown.
  */
 native user_has_weapon(index, weapon, setweapon = -1);
 
@@ -986,9 +981,9 @@ native user_has_weapon(index, weapon, setweapon = -1);
  * @param clip      Optional variable to store clip ammo to
  * @param ammo      Optional variable to store backpack ammo to
  *
- * @return          Weapon index on success, or 0 if the client is not connected
+ * @return          Weapon index on success or 0 if the client is not connected
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients an error will be thrown.
+ *                  MaxClients, an error will be thrown.
  */
 native get_user_weapon(index, &clip = 0, &ammo = 0);
 
@@ -1000,9 +995,9 @@ native get_user_weapon(index, &clip = 0, &ammo = 0);
  * @param clip      Variable to store clip ammo to
  * @param ammo      Variable to store backpack ammo to
  *
- * @return          1 on success, or 0 if the client is not connected
+ * @return          1 on success or 0 if the client is not connected
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients, or the weapon index is invalid, an error will
+ *                  MaxClients or the weapon index is invalid, an error will
  *                  be thrown.
  */
 native get_user_ammo(index, weapon, &clip, &ammo);
@@ -1012,8 +1007,8 @@ native get_user_ammo(index, weapon, &clip, &ammo);
  *
  * @note The conversion algorithm is limited to a certain range of numbers, but
  *       is guaranteed to work correctly for all numbers from 0 to 999. Outside
- *       of that range the conversion will result in an incorrect string, but
- *       not fail.
+ *       of that range, the conversion will result in an incorrect string, but
+ *       will not fail.
  * @note The conversion is to english text, there is no way to change this.
  *
  * @param num       Integer to convert
@@ -1041,7 +1036,7 @@ native get_user_team(index, team[] = "", len = 0);
  * Returns client's playing time in seconds.
  *
  * @param index     Client index
- * @param flag      If nonzero the result will not include the time it took
+ * @param flag      If nonzero, the result will not include the time it took
  *                  the client to connect.
  *
  * @return          Connection time in seconds, 0 if client index is invalid or
@@ -1054,7 +1049,7 @@ native get_user_time(index, flag = 0);
  *
  * @param index     Client index
  * @param ping      Variable to store ping in
- * @param loss      Variable to sote loss in
+ * @param loss      Variable to store loss in
  *
  * @return          1 on success, 0 if client index is invalid or the client
  *                  is not connected
@@ -1073,17 +1068,17 @@ native get_user_ping(index, &ping, &loss);
  *                    3 - aim end position from eyes (hit point for weapon)
  *                    4 - position of last bullet hit (only for Counter-Strike)
  *
- * @return          1 on succes, 0 if client is not connected
+ * @return          1 on success, 0 if client is not connected
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients an error will be thrown.
+ *                  MaxClients, an error will be thrown.
  */
 native get_user_origin(index, origin[3], mode = 0);
 
 /**
- * Retrieves all weapons in the client inventory, stores them in an array and
+ * Retrieves all weapons in the client inventory, stores them in an array, and
  * returns the inventory as a bitflag sum.
  *
- * @note Make sure that num has an initial value of 0, or the native will not
+ * @note Make sure that num has an initial value of 0 or the native will not
  *       work correctly.
  *
  * @param index     Client index
@@ -1092,7 +1087,7 @@ native get_user_origin(index, origin[3], mode = 0);
  *
  * @return          Bitflag sum of weapon indexes, 0 if client is not connected
  * @error           If the client index is not within the range of 1 to
- *                  MaxClients an error will be thrown.
+ *                  MaxClients, an error will be thrown.
  */
 native get_user_weapons(index, weapons[32], &num);
 
@@ -1151,7 +1146,7 @@ native get_user_userid(index);
  *       of the slap power. The slap direction can be influenced by the third
  *       parameter.
  *
- * @param index     Client idex
+ * @param index     Client index
  * @param power     Power of the slap
  * @param rnddir    If set to zero the player will be slapped along it's aim
  *                  vector, otherwise the direction will be randomized
@@ -1164,7 +1159,7 @@ native user_slap(index, power, rnddir = 1);
  * Kills a client.
  *
  * @param index     Client index
- * @param flag      If nonzero the death will not affect the client's score
+ * @param flag      If nonzero, the death will not affect the client's score
  *
  * @return          1 on success, 0 if client index is invalid or the client
  *                  is not connected
@@ -1270,7 +1265,7 @@ native read_args(output[], len);
  *
  * @note Should only be used inside of the client_command() forward.
  * @note This count includes the command itself. I.e. in a command with 4
- *       arguments this will return 5.
+ *       arguments, this will return 5.
  *
  * @return          Number of arguments in the command
  */
@@ -1279,7 +1274,7 @@ native read_argc();
 /**
  * Converts a flag string to a bitflag value.
  *
- * @note Example: The string "abcd" represents the sum of 1, 2, 4 and 8 - or
+ * @note Example: The string "abcd" represents the sum of 1, 2, 4, and 8 - or
  *       (1<<0)|(1<<1)|(1<<2)|(1<<3). The function will return 15.
  *
  * @param flags     Flag string to convert
@@ -1330,8 +1325,8 @@ native find_player(const flags[], ...);
 /**
  * Removes double-quotes from the beginning and end of a string.
  *
- * @note If the string only has a double-quote at either the start *or* the end
- *       and not both the function will do nothing.
+ * @note If the string only has a double-quote at either the start *or* the end,
+ *       and not both, the function will do nothing.
  * @note The function does not perform any trimming per-se. But if a
  *       double-quote is found at the beginning of the string, it will remove
  *       one ^r (carriage return) character at the end of the string if present,
@@ -1355,9 +1350,9 @@ native remove_quotes(text[]);
  * @param command   Formatting rules
  * @param ...       Variable number of formatting parameters
  *
- * @return          Lenght of formatted command string
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @return          Length of formatted command string
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native client_cmd(index, const command[], any:...);
 
@@ -1368,9 +1363,9 @@ native client_cmd(index, const command[], any:...);
  * @note This emulates a client command on the server side, and is an excellent
  *       tool to force a client to do certain actions related to the game.
  * @note The command has to stand alone in the command parameter, only add
- *       arguments using the designated paramters.
+ *       arguments using the designated parameters.
  * @note Commands emulated using this function will not trigger plugin command
- *       hooks. For an alternative that does, see amxclient_cmd().
+ *       hooks. For an alternative that does, see amxclient_cmd()
  *
  * @param index         Client index, use 0 to execute from all clients
  * @param command       Client command to execute on
@@ -1378,8 +1373,8 @@ native client_cmd(index, const command[], any:...);
  * @param arg2          Optional command arguments
  *
  * @noreturn
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
 
@@ -1390,9 +1385,9 @@ native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "
  * @note This emulates a client command on the server side, and is an excellent
  *       tool to force a client to do certain actions related to the game.
  * @note The command has to stand alone in the command parameter, only add
- *       arguments using the designated paramters.
+ *       arguments using the designated parameters.
  * @note Commands emulated using this function will trigger other plugin's
- *       command hooks. For an alternative that doesn't, see engclient_cmd().
+ *       command hooks. For an alternative that doesn't, see engclient_cmd()
  *
  * @param index         Client index, use 0 to execute from all clients
  * @param command       Client command to execute on
@@ -1400,8 +1395,8 @@ native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "
  * @param arg2          Optional command arguments
  *
  * @noreturn
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
 
@@ -1412,7 +1407,7 @@ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "
  *       client-controlled input (including client names) to this function
  *       without sanitizing it first.
  * @note The queued commands will be executed by the engine on the next frame.
- *       If you require them to be executed immediately, see server_exec().
+ *       If you require them to be executed immediately, see server_exec()
  *
  * @param command   Formatting rules
  * @param ...       Variable number of formatting parameters
@@ -1453,7 +1448,7 @@ native Float:get_gametime();
  * Returns the maxplayers setting of the current server, that is how many
  * clients it supports.
  *
- * @note As of AMXX 1.8.3 this value is also exposed through a dynamic constant
+ * @note As of AMXX 1.8.3, this value is also exposed through a dynamic constant
  *       via the MaxClients variable, declared in amxconst.inc
  *
  * @return      Maxplayers setting
@@ -1463,7 +1458,7 @@ native get_maxplayers();
 /**
  * Retrieves the name of the currently played mod.
  *
- * @note This retrieves the short name of the mod. Example: for Counter-Strike
+ * @note This retrieves the short name of the mod. Example: for Counter-Strike,
  *       it will copy "cstrike" to the buffer.
  *
  * @param name      Buffer to copy mod name to
@@ -1489,7 +1484,7 @@ native get_modname(name[], len);
 native get_time(const format[], output[], len);
 
 /**
- * Retrieves the provided time using using the specified format string.
+ * Retrieves the provided time using the specified format string.
  *
  * @note Uses the strftime C function. For a list of valid format parameters,
  *       see: http://cplusplus.com/reference/clibrary/ctime/strftime.html
@@ -1512,12 +1507,11 @@ native format_time(output[], len, const format[], time = -1);
  * @param offset    Optional offset value in seconds
  *
  * @return          Unix time stamp
- * @error
  */
 native get_systime(offset = 0);
 
 /**
- * Converts time string to unix time stamp.
+ * Converts time strings to unix time stamp.
  *
  * @note Uses the strptime C function. For a list of valid format parameters,
  *       see: http://www.cplusplus.com/reference/ctime/strftime/
@@ -1528,7 +1522,7 @@ native get_systime(offset = 0);
  *
  * @param input     Time string to convert
  * @param format    Formatting information for conversion
- * @param time      If different from -1 the converted time will be added to
+ * @param time      If different from -1, the converted time will be added to
  *                  this time stamp
  *
  * @return          Unix time stamp
@@ -1551,7 +1545,7 @@ native parse_time(const input[], const format[], time = -1);
  *                              map start
  *                        "d" - time interval is treated as absolute time before
  *                              map change
- * @param repeat        If the "a" flag is set the task will be repeated this
+ * @param repeat        If the "a" flag is set, the task will be repeated this
  *                      many times
  *
  * @noreturn
@@ -1594,9 +1588,9 @@ native task_exists(id = 0, outside = 0);
 /**
  * Sets the specified admin flags to a client.
  *
- * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc
+ * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc
  * @note This function just adds the flags using a bitwise-or operation. After it
- *       has run the flags may not exactly equal the specified bitflag sum.
+ *       has run, the flags may not exactly equal the specified bitflag sum.
  * @note AMXX stores multiple sets of flags internally, but only flag set
  *       0 is actively used. You should not change the value of the third
  *       parameter from the default.
@@ -1614,7 +1608,7 @@ native set_user_flags(index, flags = -1, id = 0);
 /**
  * Returns the client's admin flags as a bitflag sum.
  *
- * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc
+ * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc
  * @note AMXX stores multiple sets of flags internally, but only flag set
  *       0 is actively used. You should not change the value of the second
  *       parameter from the default.
@@ -1631,7 +1625,7 @@ native get_user_flags(index, id = 0);
 /**
  * Removes the specified admin flags from a client.
  *
- * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc
+ * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc
  * @note This function just removes the flags using a bitwise-and operation.
  * @note AMXX stores multiple sets of flags internally, but only flag set
  *       0 is actively used. You should not change the value of the third
@@ -1651,7 +1645,7 @@ native remove_user_flags(index, flags = -1, id = 0);
  * Registers a callback to be called when the client executes a command from the
  * console.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  * @note Opting in to FlagManager enables the admin privileges to be overwritten
  *       by the end user via the cmdaccess.ini config file.
@@ -1676,7 +1670,7 @@ native register_clcmd(const client_cmd[], const function[], flags = -1, const in
  * Registers a callback to be called when the client or server executes a
  * command from the console.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  * @note Opting in to FlagManager enables the admin privileges to be overwritten
  *       by the end user via the cmdaccess.ini config file.
@@ -1701,7 +1695,7 @@ native register_concmd(const cmd[], const function[], flags = -1, const info[] =
  * Registers a callback to be called when the server executes a command from the
  * console.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param client_cmd    Command to register
@@ -1718,7 +1712,7 @@ native register_srvcmd(const server_cmd[], const function[], flags = -1, const i
 /**
  * Retrieves information about a client command.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1730,27 +1724,27 @@ native register_srvcmd(const server_cmd[], const function[], flags = -1, const i
  * @param flag      Only considers commands that can be accessed with
  *                  the specified privilege flags
  *
- * @return          1 on succes, 0 if command was not found
+ * @return          1 on success, 0 if command was not found
  */
 native get_clcmd(index, command[], len1, &flags, info[], len2, flag);
 
 /**
  * Returns number of registered client commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
  *                  the specified privilege flags
  *
- * @return          Number of registered client commants
+ * @return          Number of registered client commands
  */
 native get_clcmdsnum(flag);
 
 /**
  * Retrieves information about a server command.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1762,27 +1756,27 @@ native get_clcmdsnum(flag);
  * @param flag      Only considers commands that can be accessed with
  *                  the specified privilege flags
  *
- * @return          1 on succes, 0 if command was not found
+ * @return          1 on success, 0 if command was not found
  */
 native get_srvcmd(index, server_cmd[], len1, &flags, info[], len2, flag);
 
 /**
  * Returns number of registered server commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
  *                  the specified privilege flags
  *
- * @return          Number of registered server commants
+ * @return          Number of registered server commands
  */
 native get_srvcmdsnum(flag);
 
 /**
  * Retrieves information about a console command.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param index     Command index
@@ -1797,14 +1791,14 @@ native get_srvcmdsnum(flag);
  *                  positive will only consider client commands, otherwise
  *                  all console commands will be considered
  *
- * @return          1 on succes, 0 if command was not found
+ * @return          1 on success, 0 if command was not found
  */
 native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id = -1);
 
 /**
  * Returns the parent plugin id of a console command.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param cid           Command index
@@ -1821,7 +1815,7 @@ native get_concmd_plid(cid, flag_mask, id_type);
 /**
  * Returns number of registered console commands.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param flag      Only considers commands that can be accessed with
@@ -1830,7 +1824,7 @@ native get_concmd_plid(cid, flag_mask, id_type);
  *                  positive will only consider client commands, otherwise
  *                  all console commands will be considered
  *
- * @return          Number of registered console commants
+ * @return          Number of registered console commands
  */
 native get_concmdsnum(flag, id = -1);
 
@@ -1860,8 +1854,8 @@ native register_menucmd(menuid, keys, const function[]);
 /**
  * Returns if the client is watching a menu.
  *
- * @note If there is no menu the id is 0. If the id is negative then the client
- *       views a VGUI menu. Otherwise the id is an id acquired from the
+ * @note If there is no menu, the id is 0. If the id is negative, then the client
+ *       views a VGUI menu. Otherwise, the id is an id acquired from the
  *       register_menuid() function.
  *
  * @param index     Client index
@@ -1877,7 +1871,7 @@ native get_user_menu(index, &id, &keys);
 /**
  * Forces the server to execute the command queue immediately.
  *
- * @note Commands can be added to the queue using server_cmd().
+ * @note Commands can be added to the queue using server_cmd()
  *
  * @noreturn
  */
@@ -1888,7 +1882,7 @@ native server_exec();
  *
  * @note The sample must be precached using precache_sound() so it is available
  *       in the engine's sound table.
- * @note For a list of available channels see CHAN_* constants in amxconst.inc,
+ * @note For a list of available channels, see CHAN_* constants in amxconst.inc,
  *       sounds emitted from the same channel will override each other.
  * @note There are helpful reference constants in amxconst.inc for sound volume
  *       (VOL_*), attenuation (ATTN_*), flags (SND_*), and pitch (PITCH_*).
@@ -1954,7 +1948,7 @@ native get_user_msgname(msgid, name[], len);
  *
  * @note Variables declared with the "public" specifier are accessible by-name
  *       from outside of the declaring plugin.
- * @note If multiple plugins declare the same public variable this native will
+ * @note If multiple plugins declare the same public variable, this native will
  *       still return a unique id.
  *
  * @param name      Variable name
@@ -1975,7 +1969,7 @@ native xvar_exists(const name[]);
 /**
  * Returns the integer value of a public variable.
  *
- * @note If multiple plugins declare the same public variable they are not
+ * @note If multiple plugins declare the same public variable, they are not
  *       automatically synchronized. The xvar system accesses only one of all
  *       public variables directly. Xvars have to be read through the natives or
  *       the value will be incorrect.
@@ -1989,7 +1983,7 @@ native get_xvar_num(id);
 /**
  * Returns the float value of a public variable.
  *
- * @note If multiple plugins declare the same public variable they are not
+ * @note If multiple plugins declare the same public variable, they are not
  *       automatically synchronized. The xvar system accesses only one of all
  *       public variables directly. Xvars have to be read through the natives or
  *       the value will be incorrect.
@@ -2003,7 +1997,7 @@ native Float:get_xvar_float(id);
 /**
  * Sets the integer value of a public variable.
  *
- * @note If multiple plugins declare the same public variable they are not
+ * @note If multiple plugins declare the same public variable, they are not
  *       automatically synchronized. The xvar system accesses only one of all
  *       public variables directly. Xvars have to be set through the natives or
  *       the xvar will not be updated.
@@ -2012,14 +2006,14 @@ native Float:get_xvar_float(id);
  * @param value     Value to set
  *
  * @noreturn
- * @error           If an invalid xvar id is specified an error will be thrown.
+ * @error           If an invalid xvar id is specified, an error will be thrown.
  */
 native set_xvar_num(id, value = 0);
 
 /**
  * Sets the float value of a public variable.
  *
- * @note If multiple plugins declare the same public variable they are not
+ * @note If multiple plugins declare the same public variable, they are not
  *       automatically synchronized. The xvar system accesses only one of all
  *       public variables directly. Xvars have to be set through the natives or
  *       the xvar will not be updated.
@@ -2028,7 +2022,7 @@ native set_xvar_num(id, value = 0);
  * @param value     Value to set
  *
  * @noreturn
- * @error           If an invalid xvar id is specified an error will be thrown.
+ * @error           If an invalid xvar id is specified, an error will be thrown.
  */
 native set_xvar_float(id, Float:value = 0.0);
 
@@ -2044,7 +2038,7 @@ native is_module_loaded(const name[]);
 /**
  * Retrieves info about a module by module index.
  *
- * @note For a list of possible status flags see module_* constants in
+ * @note For a list of possible status flags, see module_* constants in
  *       amxconst.inc
  *
  * @param id            Module id
@@ -2056,7 +2050,7 @@ native is_module_loaded(const name[]);
  * @param versionLen    Maximum version buffer size
  * @param status        Variable to store module status to
  *
- * @return              Module id on succes, -1 on invalid module
+ * @return              Module id on success, -1 on invalid module
  */
 native get_module(id, name[], nameLen, author[], authorLen, version[], versionLen, &status);
 
@@ -2070,11 +2064,11 @@ native get_modulesnum();
 /**
  * Returns if a plugin is loaded by registered name or filename.
  *
- * @note An example for a registered name would be "Admin Base" while a possible
- *       filename would be "admin.amxx"
- * @note Prior to AMXX 1.80 this function would only search for plugins
+ * @note An example for a registered name would be "Admin Base", while a possible
+ *       filename would be "admin.amxx".
+ * @note Prior to AMXX 1.80, this function would only search for plugins
  *       registered names, not the filename.
- * @note The plugin name matching is case insensitive while the filename
+ * @note The plugin name matching is case insensitive, while the filename
  *       matching is case sensitive.
  *
  * @param name          Plugin name or filename
@@ -2116,7 +2110,7 @@ native get_pluginsnum();
 /**
  * Pauses a plugin so it will not be executed until it is unpaused.
  *
- * @note This used to be able to pause specific functions but this functionality
+ * @note This used to be able to pause specific functions, but this functionality
  *       (along with the flags "b" and "e") has been deprecated.
  * @note If used without flag "c" this will pause the calling plugin.
  *
@@ -2136,7 +2130,7 @@ native pause(const flag[], const param1[] = "", const param2[] = "");
 /**
  * Unpauses a plugin so it will resume execution if it was previously paused.
  *
- * @note This used to be able to unpause specific functions but this
+ * @note This used to be able to unpause specific functions, but this
  *       functionality (along with the flags "b" and "e") has been deprecated.
  * @note Without specifying flag "c" this function will do nothing, as a plugin
  *       is incapable of unpausing itself. This is a relict of the deprecated
@@ -2159,10 +2153,10 @@ native unpause(const flag[], const param1[] = "", const param2[] = "");
  *
  * @note This only sets up the function call and covers the pre-requisites.
  *       Push parameters using the callfunc_push_* set of functions. The call
- *       will be executed only upon using callfunc_end().
+ *       will be executed only upon using callfunc_end()
  *
  * @param func      Function name
- * @param plugin    Plugin filename. If empty the calling plugin is targeted.
+ * @param plugin    Plugin filename, if empty the calling plugin is targeted
  *                  The filename has to be the full exact name (e.g. stats.amxx)
  *
  * @return           1 on success
@@ -2179,11 +2173,11 @@ native callfunc_begin(const func[], const plugin[] = "");
  *
  * @note This only sets up the function call and covers the pre-requisites.
  *       Push parameters using the callfunc_push_* set of functions. The call
- *       will be executed only upon using callfunc_end().
- * @note The function id can be retrieved by get_func_id().
+ *       will be executed only upon using callfunc_end()
+ * @note The function id can be retrieved by get_func_id()
  *
  * @param func      Function id
- * @param plugin    Plugin filename. If empty the calling plugin is targeted.
+ * @param plugin    Plugin filename, if empty the calling plugin is targeted
  *                  The filename has to be the full exact name (e.g. stats.amxx)
  *
  * @return           1 on success
@@ -2195,11 +2189,11 @@ native callfunc_begin(const func[], const plugin[] = "");
 native callfunc_begin_i(func, plugin = -1);
 
 /**
- * Retrieves a functions id for use with callfunc_begin_i().
+ * Retrieves a functions id for use with callfunc_begin_i()
  *
  * @param funcName  Function name
- * @param pluginId  Plugin id. If -1 the calling plugin is targeted. The plugin
- *                  id can be retrieved using find_plugin_byfile()
+ * @param pluginId  Plugin id, if -1 the calling plugin is targeted
+ *                  The plugin id can be retrieved using find_plugin_byfile()
  *
  * @return          >0 Function id on success
  *                  -1 if plugin or function was not found
@@ -2263,7 +2257,7 @@ native callfunc_push_floatrf(&Float:value);
  *       only kept for special backwards compatibility.
  *
  * @param VALUE     String to push
- * @param copyback  If true any changes made in the called function will be
+ * @param copyback  If true, any changes made in the called function will be
  *                  copied back to the calling plugin
  *
  * @noreturn
@@ -2280,7 +2274,7 @@ native callfunc_push_str(const VALUE[], bool:copyback = true);
  *
  * @param VALUE         Array to push
  * @param array_size    Size of the array
- * @param copyback      If true any changes made in the called function will be
+ * @param copyback      If true, any changes made in the called function will be
  *                      copied back to the calling plugin
  *
  * @noreturn
@@ -2295,7 +2289,7 @@ native callfunc_push_array(const VALUE[], array_size, bool:copyback = true);
  * @return       1 on success
  *              -1 if the plugin was not found
  *              -2 if the function was not found
- * @error       If called without initiating a callfunc an error is thrown.
+ * @error       If called without initiating a callfunc, an error is thrown.
  */
 native callfunc_end();
 
@@ -2315,7 +2309,7 @@ forward inconsistent_file(id, const filename[], reason[64]);
  * Forces the clients and server to be running with the same version of a
  * specified file.
  *
- * @note For a list of possible enforcement types see the force_* constants
+ * @note For a list of possible enforcement types, see the force_* constants
  *       in amxconst.inc
  *
  * @param force_type    Enforcement type
@@ -2351,7 +2345,7 @@ native md5_file(const file[], md5buffer[34]);
 /**
  * Returns the internal flags set on the plugin's state.
  *
- * @param hdr       If nonzero the function will return the pcode rather than
+ * @param hdr       If nonzero, the function will return the pcode rather than
  *                  state flags
  * @param plid      Plugin id, -1 to target calling plugin
  *
@@ -2360,7 +2354,7 @@ native md5_file(const file[], md5buffer[34]);
 native plugin_flags(hdr = 0, plid = -1);
 
 /**
- * Allows plugins to declare module dependencies using require_module().
+ * Allows plugins to declare module dependencies using require_module()
  *
  * @deprecated Module dependency has been automatically handled by the compiler
  *             since AMXX 1.50, released in 2005. This forward is no longer
@@ -2385,7 +2379,7 @@ native require_module(const module[]);
 /**
  * Returns if the server is 64 bit.
  *
- * @deprecated As a result of Valve dropping support for 64bit binaries AMXX is
+ * @deprecated As a result of Valve dropping support for 64bit binaries, AMXX is
  *             also not shipping 64bit builds anymore. This native is basically
  *             guaranteed to return 0.
  *
@@ -2425,8 +2419,8 @@ forward plugin_natives();
  * @note Style 1 natives are deprecated. Plugins should not use them, they might
  *       break.
  * @note Style 1 natives work a little different. Instead of passing plugin id
- *       and number of parameters the handler should be prototyped just like the
- *       native would be called. For each by-reference parameter the plugin
+ *       and number of parameters, the handler should be prototyped just like the
+ *       native would be called. For each by-reference parameter, the plugin
  *       then has to use param_convert() to properly use them.
  * @note A native should *never* recurse. Bad things will happen.
  *
@@ -2476,14 +2470,14 @@ native log_error(error, const fmt[], any:...);
  * @deprecated Style 1 natives are deprecated and should be converted to
  *             style 0. This should not be used.
  *
- * @note Only needs to be called this if the native was registered with style 1.
+ * @note This only needs to be called if the native was registered with style 1.
  * @note Remember that arrays (and strings) are always by-reference and need to
  *       be converted.
  *
  * @param num       Argument to convert, starting from 1
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 0, an error will be thrown.
  */
 native param_convert(num);
@@ -2496,7 +2490,7 @@ native param_convert(num);
  * @param maxlen    Maximum size of buffer
  *
  * @return          Number of cells copied to buffer
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native get_string(param, dest[], maxlen);
@@ -2509,7 +2503,7 @@ native get_string(param, dest[], maxlen);
  * @param maxlen    Maximum size of buffer
  *
  * @return          Number of cells copied from buffer
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native set_string(param, dest[], maxlen);
@@ -2520,7 +2514,7 @@ native set_string(param, dest[], maxlen);
  * @param param     Argument to retrieve, starting from 1
  *
  * @return          Integer value
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native get_param(param);
@@ -2531,7 +2525,7 @@ native get_param(param);
  * @param param     Argument to retrieve, starting from 1
  *
  * @return          Float value
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native Float:get_param_f(param);
@@ -2543,7 +2537,7 @@ native Float:get_param_f(param);
  * @param param     Argument to retrieve, starting from 1
  *
  * @return          Integer value
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native get_param_byref(param);
@@ -2555,7 +2549,7 @@ native get_param_byref(param);
  * @param param     Argument to retrieve, starting from 1
  *
  * @return          Float value
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native Float:get_float_byref(param);
@@ -2568,7 +2562,7 @@ native Float:get_float_byref(param);
  * @param value     Value to set parameter to
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native set_param_byref(param, value);
@@ -2581,7 +2575,7 @@ native set_param_byref(param, value);
  * @param value     Value to set parameter to
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native set_float_byref(param, Float:value);
@@ -2594,7 +2588,7 @@ native set_float_byref(param, Float:value);
  * @param maxlen    Size of buffer
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native get_array(param, dest[], size);
@@ -2607,7 +2601,7 @@ native get_array(param, dest[], size);
  * @param maxlen    Size of buffer
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native get_array_f(param, Float:dest[], size);
@@ -2620,7 +2614,7 @@ native get_array_f(param, Float:dest[], size);
  * @param maxlen    Size of buffer
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native set_array(param, const source[], size);
@@ -2633,7 +2627,7 @@ native set_array(param, const source[], size);
  * @param maxlen    Size of buffer
  *
  * @noreturn
- * @error           If used outside of a native callback or the native was
+ * @error           If used outside of a native callback, or the native was
  *                  created with style 1, an error will be thrown.
  */
 native set_array_f(param, const Float:source[], size);
@@ -2665,7 +2659,7 @@ native set_error_filter(const handler[]);
 /**
  * Returns a trace handle for the item at the top of the traced call stack.
  *
- * @note Intended for use inside an error handler set with set_error_filter().
+ * @note Intended for use inside an error handler set with set_error_filter()
  *
  * @return      Trace handle, 0 if no debugging information is available
  */
@@ -2734,7 +2728,7 @@ native dbg_fmt_error(buffer[], maxLength);
  *
  * @return          1 if handler is set successfully, 0 otherwise (called
  *                  outside of plugin_native() forward)
- * @error           If an invalid callback function is provided an error is
+ * @error           If an invalid callback function is provided, an error is
  *                  thrown.
  */
 native set_native_filter(const handler[]);
@@ -2776,7 +2770,7 @@ native set_module_filter(const handler[]);
  *       plugin_natives() forward.
  * @note The message will automatically be tagged with the plugin's name and the
  *       log will include a timestamp with the message.
- * @note For a list of possible error codes see AMX_* constants in amxconst.inc
+ * @note For a list of possible error codes, see AMX_* constants in amxconst.inc
  *
  * @param error     Error code
  * @param fmt       Formatting rules
@@ -2805,9 +2799,9 @@ native module_exists(const logtag[]);
  * Returns if a specific library or class is loaded.
  *
  * @note This is the newer version of module_exists(), enabling users to
- *       distinguish between libraries and classes while module_exists() always
+ *       distinguish between libraries and classes, while module_exists() always
  *       checks for both types.
- * @note For a list of possible types see the LibType enum in amxconst.inc
+ * @note For a list of possible types, see the LibType enum in amxconst.inc
  *
  * @param library   Library/Class shortname
  * @param type      Type to search for
@@ -2826,7 +2820,7 @@ native LibraryExists(const library[], LibType:type);
  *
  * @return          Valid hudchannel (1-4)
  * @error           If the index is not within the range of 1 to MaxClients or
- *                  the client is not connected an error will be thrown.
+ *                  the client is not connected, an error will be thrown.
  */
 native next_hudchannel(player);
 
@@ -2862,7 +2856,7 @@ native CreateHudSyncObj(num = 0, ...);
  * @note This functions return value behaves differently depending on what is
  *       used as the client index: If 0 is specified, then the function will
  *       return 0 if nothing has been sent (no client connected). If either a
- *       single client is specified or there is at least one client connected,
+ *       single client is specified, or there is at least one client connected,
  *       the number of printed characters will refer to the message that is sent
  *       last, to the client with the highest index.
  *
@@ -2872,8 +2866,8 @@ native CreateHudSyncObj(num = 0, ...);
  * @param ...       Variable number of formatting parameters
  *
  * @return          Number of printed characters
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native ShowSyncHudMsg(target, syncObj, const fmt[], any:...);
 
@@ -2890,8 +2884,8 @@ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...);
  * @param syncObj   HUD sync object handle
  *
  * @noreturn
- * @error           If a single client is specified and the index is not
- *                  within the range of 1 to MaxClients an error will be thrown.
+ * @error           If a single client is specified and the index is not within
+ *                  the range of 1 to MaxClients, an error will be thrown.
  */
 native ClearSyncHud(target, syncObj);
 
@@ -2940,7 +2934,7 @@ native get_var_addr(any:...);
 /**
  * Returns the value of an address.
  *
- * @note Addresses can be acquired using get_var_addr().
+ * @note Addresses can be acquired using get_var_addr()
  *
  * @param addr      Variable address
  *
@@ -2953,7 +2947,7 @@ native get_addr_val(addr);
 /**
  * Sets the value of an address.
  *
- * @note Addresses can be acquired using get_var_addr().
+ * @note Addresses can be acquired using get_var_addr()
  *
  * @param addr      Variable address
  * @param val       Value to set
@@ -2967,8 +2961,8 @@ native set_addr_val(addr, val);
 /**
  * Creates a global forward that will be called in all plugins.
  *
- * @note For a list of valid stop types see the ET_* constants in amxconst.inc
- * @note For a list of valid parameter types see the FP_* constants in
+ * @note For a list of valid stop types, see the ET_* constants in amxconst.inc
+ * @note For a list of valid parameter types, see the FP_* constants in
  *       amxconst.inc
  *
  * @param name          Function name to call
@@ -2983,7 +2977,7 @@ native CreateMultiForward(const name[], stop_type, ...);
  * Creates a private forward that will be called in a single plugin.
  *
  * @note Unlike other natives expecting a plugin id, specifying -1 will not
- *       select the calling plugin and instead throw an error.
+ *       select the calling plugin, and instead throw an error.
  *
  * @param plugin_id     Plugin to call forward in. The plugin id can be
  *                      retrieved using find_plugin_byfile()
@@ -2991,7 +2985,7 @@ native CreateMultiForward(const name[], stop_type, ...);
  * @param ...           List of parameter types
  *
  * @return              Forward handle, -1 on failure
- * @error               If an invalid plugin id is specified an error will be
+ * @error               If an invalid plugin id is specified, an error will be
  *                      thrown.
  */
 native CreateOneForward(plugin_id, const name[], ...);
@@ -3002,7 +2996,7 @@ native CreateOneForward(plugin_id, const name[], ...);
  *
  * @param array         Array to prepare
  * @param size          Size of array
- * @param copyback      If nonzero modifications made by the called plugin(s)
+ * @param copyback      If nonzero, modifications made by the called plugin(s)
  *                      will be copied back to the caller
  *
  * @return              Special handle for use in ExecuteForward()
@@ -3012,7 +3006,7 @@ native PrepareArray(const array[], size, copyback = 0);
 /**
  * Executes a forward.
  *
- * @note Passing arrays requires them to be prepared using PrepareArray().
+ * @note Passing arrays requires them to be prepared using PrepareArray()
  *
  * @param forward_handle    Forward handle
  * @param ret               Variable to store return value in
@@ -3061,9 +3055,9 @@ native get_weaponid(const name[]);
 /**
  * Adds an admin to the dynamic admin storage for lookup at a later time.
  *
- * @note For a list of possible access flags see the ADMIN_* constants in
+ * @note For a list of possible access flags, see the ADMIN_* constants in
  *       amxconst.inc
- * @note For a list of possible auth flags see the FLAG_* constants in
+ * @note For a list of possible auth flags, see the FLAG_* constants in
  *       amxconst.inc
  *
  * @param AuthData      Auth information to set (can be name, IP or SteamID)
@@ -3085,11 +3079,11 @@ native admins_num();
 /**
  * Retrieves information about a dynamically stored admin.
  *
- * @note For a list of possible props see the AdminProp enum in amxconst.inc
+ * @note For a list of possible props, see the AdminProp enum in amxconst.inc
  *
  * @param num           Admin storage index
  * @param Property      Admin property to retrieve
- * @param Buffer        Buffer to copy property information to if AdminProp_Auth
+ * @param Buffer        Buffer to copy property information to, if AdminProp_Auth
  *                      or AdminProp_Password is specified
  * @param BufferSize    Maximum buffer size
  *