amxmodx: Consistency updates, typo fixes, missing return/error added

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
+ * Called just before server deactivation and subsequent unloading of the
- * unloading of the plugin.
+ * 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
+ * @note Message data and information can be retrieved using the read_log set of
- *       of functions.
+ *       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,10 +319,10 @@ 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
+ * @param message   Message to display inside the MOTD window, if this is a
- *                  filename the contents of this file will be displayed.
+ *                  filename the contents of this file will be displayed
- * @param header    Text for the MOTD header. If this is empty the servers
+ * @param header    Text for the MOTD header, if empty the servers hostname will
- *                  hostname will be displayed instead.
+ *                  be displayed instead
  *
  * @noreturn
  */
@@ -331,18 +331,21 @@ 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,7 +471,8 @@ 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[] = "", ...);
 
@@ -489,7 +498,8 @@ 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, ...);
 
@@ -530,18 +540,20 @@ native set_hudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, ef
  * 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:...);
 
@@ -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,6 +629,11 @@ 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[] = "");
 
@@ -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
+ * @param ...       Changes the native's behavior depending on how many
- *                  will return the argument value directly.
+ *                  additional parameters are provided:
- *                  If 1 additional parameter is provided, the function will
+ *                     0 - Return the argument integer value directly
- *                  store a float value in that second parameter.
+ *                     1 - Store the argument float value in the variable passed
- *                  If two additional parameters are provided, the function
+ *                         as the second parameter
- *                  will copy a string to the buffer provided in the second
+ *                     2 - Copy the argument string value to the buffer provided
- *                  parameter, using the third as the maximum buffer size.
+ *                         in the second parameter, using the third as the
+ *                         maximum buffer size
  *
- * @return          If zero additional parameters are provided, the function
+ * @return          Changes depending on how many additional parameters are
- *                  will return an integer value.
+ *                  provided:
- *                  If one additional parameter is provided, the function will
+ *                     0 - Returns the argument integer value
- *                  return the float value, converted (truncated) to an integer.
+ *                     1 - Returns the argument float value, converted
- *                  If two additional parameters are provided, the function
+ *                         (truncated) to an integer
- *                  will return the number of cells written to the buffer.
+ *                     2 - Returns the number of cells written to the buffer
  */
 native read_data(value, any:...);
 
@@ -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
+ * @param ...       If provided the attacker weapon will be stored in an
- *                  attacker weapon, and a third byref parameter will be filled
+ *                  optional second parameter, and the body hit place will be
- *                  with the hit place on the body.
+ *                  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)
@@ -1020,7 +1039,7 @@ 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);
 
@@ -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);
 
@@ -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,7 +1160,9 @@ 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);
 
@@ -1150,7 +1173,7 @@ 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);
 
@@ -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,14 +1378,14 @@ 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[] = "");
 
@@ -1377,14 +1400,14 @@ 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[] = "");
 
@@ -1484,13 +1507,13 @@ 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);
 
 /**
  * Returns the system time as a unix timestamp (number of seconds since unix
- * epoch)
+ * epoch).
  *
  * @param offset    Optional offset value in seconds
  *
@@ -1512,10 +1535,10 @@ 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);
 
@@ -1536,6 +1559,10 @@ 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);
 
@@ -1630,7 +1657,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_* 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.
@@ -1655,7 +1682,7 @@ native register_clcmd(const client_cmd[], const function[], flags=-1, const info
  * 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.
@@ -1680,7 +1707,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_* constans in
+ * @note For a list of possible access flags see the ADMIN_* constants in
  *       amxconst.inc
  *
  * @param client_cmd    Command to register
@@ -1697,7 +1724,7 @@ native register_srvcmd(const server_cmd[], const function[], flags=-1, const inf
 /**
  * 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);
 
 /**
- * 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,20 +1819,22 @@ 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
  */
@@ -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
@@ -2134,7 +2165,7 @@ 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.
@@ -2154,8 +2185,8 @@ 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()
+ *       will be executed only upon using callfunc_end().
- * @note The function id can be retrieved by get_func_id()
+ * @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.
@@ -2170,7 +2201,7 @@ 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
@@ -2239,7 +2270,7 @@ 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
@@ -2256,7 +2287,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
- *                      copied back to the calling plugin.
+ *                      copied back to the calling plugin
  *
  * @noreturn
  * @error           If called without initiating a callfunc, or the maximum
@@ -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);
 
 /**
- * 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.
  *
@@ -2627,9 +2660,11 @@ native set_array_f(param, const Float:source[], size);
  * @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[]);
 
@@ -2700,6 +2735,13 @@ native dbg_fmt_error(buffer[], maxLength);
  *       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[]);
 
@@ -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.
  */
@@ -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);
 
 /**
- * Clears the list of dynamically stored admins
+ * Clears the list of dynamically stored admins.
  *
  * @noreturn
  */