From d73f4e7ecaffb205f9b39b586c01ce6b170eddb2 Mon Sep 17 00:00:00 2001
From: Natanel Shitrit <65548905+Natanel-Shitrit@users.noreply.github.com>
Date: Thu, 24 Jun 2021 17:45:01 +0300
Subject: [PATCH] Documentation corrections and additions (#1498)

* Added `@error` documentation for every function that's missing it.
* Changed tabs to spaces (text alignment)
---
 plugins/include/clients.inc               |  8 ++++++++
 plugins/include/halflife.inc              | 18 ++++++++++--------
 plugins/include/sdkhooks.inc              |  1 +
 plugins/include/sdktools.inc              |  2 ++
 plugins/include/sdktools_client.inc       |  2 ++
 plugins/include/sdktools_functions.inc    | 22 ++++++++++++----------
 plugins/include/sdktools_gamerules.inc    | 20 ++++++++++----------
 plugins/include/sdktools_sound.inc        | 12 ++++++------
 plugins/include/sdktools_stringtables.inc |  1 +
 plugins/include/sdktools_trace.inc        |  7 +++++++
 plugins/include/sdktools_voice.inc        |  5 +++++
 plugins/include/sourcemod.inc             |  2 ++
 plugins/include/string.inc                |  3 +++
 plugins/include/timers.inc                |  3 ++-
 plugins/include/topmenus.inc              |  4 ++--
 15 files changed, 73 insertions(+), 37 deletions(-)

diff --git a/plugins/include/clients.inc b/plugins/include/clients.inc
index 346740cf..29a9aa7b 100644
--- a/plugins/include/clients.inc
+++ b/plugins/include/clients.inc
@@ -347,6 +347,7 @@ native int GetClientUserId(int client);
  *
  * @param client        Player index.
  * @return              True if player is connected to the server, false otherwise.
+ * @error               Invalid client index.
  */
 native bool IsClientConnected(int client);
 
@@ -384,6 +385,7 @@ stock bool IsPlayerInGame(int client)
  *
  * @param client        Player index.
  * @return              True if player has been authenticated, false otherwise.
+ * @error               Invalid client index.
  */
 native bool IsClientAuthorized(int client);
 
@@ -392,6 +394,7 @@ native bool IsClientAuthorized(int client);
  *
  * @param client        Player index.
  * @return              True if player is a fake client, false otherwise.
+ * @error               Invalid client index, or client not connected.
  */
 native bool IsFakeClient(int client);
 
@@ -400,6 +403,7 @@ native bool IsFakeClient(int client);
  *
  * @param client        Player index.
  * @return              True if player is the SourceTV bot, false otherwise.
+ * @error               Invalid client index, or client not connected.
  */
 native bool IsClientSourceTV(int client);
 
@@ -408,6 +412,7 @@ native bool IsClientSourceTV(int client);
  *
  * @param client        Player index.
  * @return              True if player is the Replay bot, false otherwise.
+ * @error               Invalid client index, or client not connected.
  */
 native bool IsClientReplay(int client);
 
@@ -416,6 +421,7 @@ native bool IsClientReplay(int client);
  *
  * @param client        Player index.
  * @return              True if player is an observer, false otherwise.
+ * @error               Invalid client index, client not in game, or no mod support.
  */
 native bool IsClientObserver(int client);
 
@@ -496,6 +502,7 @@ native void RemoveUserFlags(int client, AdminFlag ...);
  *
  * @param client        Player's index.
  * @param flags         Bitstring of flags to set on client.
+ * @error               Invalid client index, or client not connected.
  */
 native void SetUserFlagBits(int client, int flags);
 
@@ -548,6 +555,7 @@ native void NotifyPostAdminCheck(int client);
  *
  * @param name          Name to use.
  * @return              Client index on success, 0 otherwise.
+ * @error               No map is active.
  */
 native int CreateFakeClient(const char[] name);
 
diff --git a/plugins/include/halflife.inc b/plugins/include/halflife.inc
index c95580d7..71052d47 100644
--- a/plugins/include/halflife.inc
+++ b/plugins/include/halflife.inc
@@ -333,7 +333,7 @@ native bool IsSoundPrecached(const char[] sound);
  * @param client        Index of the client.
  * @param kv            KeyValues handle to set the menu keys and options. (Check iserverplugin.h for more information).
  * @param type          Message type to display ingame.
- * @error               Invalid client index, or client not connected.
+ * @error               Invalid client index, or client not in game.
  */
 native void CreateDialog(int client, Handle kv, DialogType type);
 
@@ -366,7 +366,7 @@ native EngineVersion GetEngineVersion();
  * @param client        Client index.
  * @param format        Formatting rules.
  * @param ...           Variable number of format parameters.
- * @error               If the client is not connected an error will be thrown.
+ * @error               Invalid client index, or client not in game.
  */
 native void PrintToChat(int client, const char[] format, any ...);
 
@@ -397,7 +397,7 @@ stock void PrintToChatAll(const char[] format, any ...)
  * @param client        Client index.
  * @param format        Formatting rules.
  * @param ...           Variable number of format parameters.
- * @error               If the client is not connected an error will be thrown.
+ * @error               Invalid client index, or client not in game.
  */
 native void PrintCenterText(int client, const char[] format, any ...);
 
@@ -428,7 +428,7 @@ stock void PrintCenterTextAll(const char[] format, any ...)
  * @param client        Client index.
  * @param format        Formatting rules.
  * @param ...           Variable number of format parameters.
- * @error               If the client is not connected an error will be thrown.
+ * @error               Invalid client index, or client not in game.
  */
 native void PrintHintText(int client, const char[] format, any ...);
 
@@ -462,7 +462,7 @@ stock void PrintHintTextToAll(const char[] format, any ...)
  * @param Kv            KeyValues handle with all the data for the panel setup (Depends
  *                      on the panel type and may be unused).
  * @param show          True to show the panel, or false to remove it from the client screen.
- * @error               If the client is not connected an error will be thrown.
+ * @error               Invalid client index, or client not in game.
  */
 native void ShowVGUIPanel(int client, const char[] name, Handle Kv=INVALID_HANDLE, bool show=true);
 
@@ -561,7 +561,7 @@ native void SetHudTextParamsEx(float x, float y, float holdTime, int color1[4],
  * @param ...           Message formatting parameters.
  * @return              -1 on failure, anything else on success.
  *                      This function fails if the mod does not support it.
- * @error               Client not in-game, or sync object not valid.
+ * @error               Invalid client index, client not in game, or sync object not valid.
  */
 native int ShowSyncHudText(int client, Handle sync, const char[] message, any ...);
 
@@ -579,7 +579,7 @@ native int ShowSyncHudText(int client, Handle sync, const char[] message, any ..
  *
  * @param client        Client index to send the message to.
  * @param sync          Synchronization object.
- * @error               Client not in-game, or sync object not valid.
+ * @error               Invalid client index, client not in game, or sync object not valid.
  */
 native void ClearSyncHud(int client, Handle sync);
 
@@ -599,6 +599,7 @@ native void ClearSyncHud(int client, Handle sync);
  * @return              -1 on failure (lack of mod support).
  *                      Any other return value is the channel number that was
  *                      used to render the text.
+ * @error               Invalid client index, or client not in game.
  */
 native int ShowHudText(int client, int channel, const char[] message, any ...);
 
@@ -610,7 +611,7 @@ native int ShowHudText(int client, int channel, const char[] message, any ...);
  * @param msg           Contents of the panel, it can be treated as an url, filename or plain text
  *                      depending on the type parameter (WARNING: msg has to be 192 bytes maximum!)
  * @param type          Determines the way to treat the message body of the panel.
- * @error               If the client is not connected an error will be thrown.
+ * @error               Invalid client index, or client not in game.
  */
 stock void ShowMOTDPanel(int client, const char[] title, const char[] msg, int type=MOTDPANEL_TYPE_INDEX)
 {
@@ -632,6 +633,7 @@ stock void ShowMOTDPanel(int client, const char[] title, const char[] msg, int t
  * @param time          Duration to hold the panel on the client's screen.
  * @param ip            Destination IP.
  * @param password      Password to connect to the destination IP. The client will be able to see this.
+ * @error               Invalid client index, or client not in game.
  */
 stock void DisplayAskConnectBox(int client, float time, const char[] ip, const char[] password = "")
 {
diff --git a/plugins/include/sdkhooks.inc b/plugins/include/sdkhooks.inc
index c1956dd5..0d86f5c4 100644
--- a/plugins/include/sdkhooks.inc
+++ b/plugins/include/sdkhooks.inc
@@ -424,6 +424,7 @@ native void SDKUnhook(int entity, SDKHookType type, SDKHookCB callback);
  * @param weapon         Weapon index (orangebox and later) or -1 for unspecified
  * @param damageForce    Velocity of damage force
  * @param damagePosition Origin of damage
+ * @error                Invalid entity, attacker, inflictor, or weapon entity.
  */
 native void SDKHooks_TakeDamage(int entity, int inflictor, int attacker,
 		float damage, int damageType=DMG_GENERIC, int weapon=-1,
diff --git a/plugins/include/sdktools.inc b/plugins/include/sdktools.inc
index a19caf4f..1ebb51e6 100644
--- a/plugins/include/sdktools.inc
+++ b/plugins/include/sdktools.inc
@@ -146,6 +146,7 @@ native bool PrepSDKCall_SetAddress(Address addr);
  * @param source        Whether to look in Offsets or Signatures.
  * @param name          Name of the property to find.
  * @return              True on success, false if nothing was found.
+ * @error               Invalid game config Handle.
  */
 native bool PrepSDKCall_SetFromConf(Handle gameconf, SDKFuncConfSource source, const char[] name);
 
@@ -168,6 +169,7 @@ native void PrepSDKCall_SetReturnInfo(SDKType type, SDKPassMethod pass, int decf
  * @param pass          How the data is passed in C++.
  * @param decflags      Flags on decoding from the plugin to C++.
  * @param encflags      Flags on encoding from C++ to the plugin.
+ * @error               Parameter limit for SDK calls reached.
  */
 native void PrepSDKCall_AddParameter(SDKType type, SDKPassMethod pass, int decflags=0, int encflags=0);
 
diff --git a/plugins/include/sdktools_client.inc b/plugins/include/sdktools_client.inc
index dfb5e160..4af804ef 100644
--- a/plugins/include/sdktools_client.inc
+++ b/plugins/include/sdktools_client.inc
@@ -39,6 +39,7 @@
  * Sets the client to an inactive state waiting for a new map
  *
  * @param client        The client index
+ * @error               Invalid client index.
  */
 native void InactivateClient(int client);
 
@@ -46,5 +47,6 @@ native void InactivateClient(int client);
  * Reconnect a client without dropping the netchannel
  *
  * @param client        The client index
+ * @error               Invalid client index.
  */
 native void ReconnectClient(int client);
diff --git a/plugins/include/sdktools_functions.inc b/plugins/include/sdktools_functions.inc
index 8acbd81c..b5d5cf47 100644
--- a/plugins/include/sdktools_functions.inc
+++ b/plugins/include/sdktools_functions.inc
@@ -123,7 +123,7 @@ native void SlapPlayer(int client, int health=5, bool sound=true);
  *                      Use -1 to start from the first entity.
  * @param classname     Classname of the entity to find.
  * @return              Entity index >= 0 if found, -1 otherwise.
- * @error               Lack of mod support or invalid start entity.
+ * @error               Invalid start entity or lack of mod support.
  */
 native int FindEntityByClassname(int startEnt, const char[] classname);
 
@@ -133,7 +133,7 @@ native int FindEntityByClassname(int startEnt, const char[] classname);
  * @param client        Player's index.
  * @param ang           Destination vector to store the client's eye angles.
  * @return              True on success, false on failure.
- * @error               Invalid client index, client not in game, or no mod support.
+ * @error               Invalid client index, client not in game, or lack of mod support.
  */
 native bool GetClientEyeAngles(int client, float ang[3]);
 
@@ -145,7 +145,7 @@ native bool GetClientEyeAngles(int client, float ang[3]);
  * @param classname         Entity classname.
  * @param ForceEdictIndex   Edict index used by the created entity (ignored on Orangebox and above).
  * @return                  Entity index on success, or -1 on failure.
- * @error                   Invalid edict index, or no mod support.
+ * @error                   Invalid edict index, no map is running, or lack of mod support.
  */
 native int CreateEntityByName(const char[] classname, int ForceEdictIndex=-1);
 
@@ -154,7 +154,7 @@ native int CreateEntityByName(const char[] classname, int ForceEdictIndex=-1);
  *
  * @param entity        Entity index of the created entity.
  * @return              True on success, false otherwise.
- * @error               Invalid entity index, or no mod support.
+ * @error               Invalid entity index or lack of mod support.
  */
 native bool DispatchSpawn(int entity);
 
@@ -165,7 +165,7 @@ native bool DispatchSpawn(int entity);
  * @param keyName       Name of the key.
  * @param value         String value.
  * @return              True on success, false otherwise.
- * @error               Invalid entity index, or no mod support.
+ * @error               Invalid entity index or lack of mod support.
  */
 native bool DispatchKeyValue(int entity, const char[] keyName, const char[] value);
 
@@ -176,7 +176,7 @@ native bool DispatchKeyValue(int entity, const char[] keyName, const char[] valu
  * @param keyName       Name of the key.
  * @param value         Floating point value.
  * @return              True on success, false otherwise.
- * @error               Invalid entity index, or no mod support.
+ * @error               Invalid entity index or lack of mod support.
  */
 native bool DispatchKeyValueFloat(int entity, const char[] keyName, float value);
 
@@ -187,7 +187,7 @@ native bool DispatchKeyValueFloat(int entity, const char[] keyName, float value)
  * @param keyName       Name of the key.
  * @param vec           Vector value.
  * @return              True on success, false otherwise.
- * @error               Invalid entity index, or no mod support.
+ * @error               Invalid entity index or lack of mod support.
  */
 native bool DispatchKeyValueVector(int entity, const char[] keyName, const float vec[3]);
 
@@ -266,7 +266,7 @@ native int GetTeamEntity(int teamIndex);
  *
  * @param entity        Entity index.
  * @param model         Model name.
- * @error               Invalid entity index, or no mod support.
+ * @error               Invalid entity index or lack of mod support.
  */
 native void SetEntityModel(int entity, const char[] model);
 
@@ -297,6 +297,7 @@ native bool GetPlayerJingleFile(int client, char[] hex, int maxlength);
  *
  * @param in            Buffer to store the input traffic velocity.
  * @param out           Buffer to store the output traffic velocity.
+ * @error               Lack of mod support.
  */
 native void GetServerNetStats(float &inAmount, float &outAmout);
 
@@ -325,7 +326,7 @@ native void ActivateEntity(int entity);
  * @param client        Player's index.
  * @param key           Key string.
  * @param value         Value string.
- * @error               Invalid client index, or client not connected.
+ * @error               Invalid client index, client not connected, or lack of mod support.
  */
 native void SetClientInfo(int client, const char[] key, const char[] value);
 
@@ -334,7 +335,7 @@ native void SetClientInfo(int client, const char[] key, const char[] value);
  *
  * @param client        Player's index.
  * @param name          New name.
- * @error               Invalid client index, or client not connected.
+ * @error               Invalid client index, client not connected, or lack of mod support.
  */
 native void SetClientName(int client, const char[] name);
 
@@ -347,5 +348,6 @@ native void SetClientName(int client, const char[] name);
  * @param ammotype      Type of ammo to give to player.
  * @param suppressSound If true, don't play the ammo pickup sound.
  * @return              Amount of ammo actually given.
+ * @error               Lack of mod support.
  */
 native int GivePlayerAmmo(int client, int amount, int ammotype, bool suppressSound=false);
diff --git a/plugins/include/sdktools_gamerules.inc b/plugins/include/sdktools_gamerules.inc
index 4df43fcd..66ba3b5c 100644
--- a/plugins/include/sdktools_gamerules.inc
+++ b/plugins/include/sdktools_gamerules.inc
@@ -80,7 +80,7 @@ enum RoundState {
  *                      only used as a fallback in case detection fails.
  * @param element       Element # (starting from 0) if property is an array.
  * @return              Value at the given property offset.
- * @error               Not supported.
+ * @error               Prop type is not an integer, or lack of mod support.
  */
 native int GameRules_GetProp(const char[] prop, int size=4, int element=0);
 
@@ -94,7 +94,7 @@ native int GameRules_GetProp(const char[] prop, int size=4, int element=0);
  *                      only used as a fallback in case detection fails.
  * @param element       Element # (starting from 0) if property is an array.
  * @param changeState   This parameter is ignored.
- * @error               Not supported.
+ * @error               Prop type is not an integer, or lack of mod support.
  */
 native void GameRules_SetProp(const char[] prop, any value, int size=4, int element=0, bool changeState=false);
 
@@ -104,7 +104,7 @@ native void GameRules_SetProp(const char[] prop, any value, int size=4, int elem
  * @param prop          Property name.
  * @param element       Element # (starting from 0) if property is an array.
  * @return              Value at the given property offset.
- * @error               Not supported.
+ * @error               Prop type is not a float, or lack of mod support.
  */
 native float GameRules_GetPropFloat(const char[] prop, int element=0);
 
@@ -115,7 +115,7 @@ native float GameRules_GetPropFloat(const char[] prop, int element=0);
  * @param value         Value to set.
  * @param element       Element # (starting from 0) if property is an array.
  * @param changeState   This parameter is ignored.
- * @error               Not supported.
+ * @error               Prop type is not a float, or lack of mod support.
  */
 native void GameRules_SetPropFloat(const char[] prop, float value, int element=0, bool changeState=false);
 
@@ -127,7 +127,7 @@ native void GameRules_SetPropFloat(const char[] prop, float value, int element=0
  * @return              Entity index at the given property.
  *                      If there is no entity, or the entity is not valid,
  *                      then -1 is returned.
- * @error               Not supported.
+ * @error               Prop type is not an entity, or lack of mod support.
  */
 native int GameRules_GetPropEnt(const char[] prop, int element=0);
 
@@ -138,7 +138,7 @@ native int GameRules_GetPropEnt(const char[] prop, int element=0);
  * @param other         Entity index to set, or -1 to unset.
  * @param element       Element # (starting from 0) if property is an array.
  * @param changeState   This parameter is ignored.
- * @error               Not supported.
+ * @error               Prop type is not an entity, invalid entity, or lack of mod support.
  */
 native void GameRules_SetPropEnt(const char[] prop, int other, int element=0, bool changeState=false);
 
@@ -148,7 +148,7 @@ native void GameRules_SetPropEnt(const char[] prop, int other, int element=0, bo
  * @param prop          Property name.
  * @param vec           Vector buffer to store data in.
  * @param element       Element # (starting from 0) if property is an array.
- * @error               Not supported.
+ * @error               Prop type is not a vector, or lack of mod support.
  */
 native void GameRules_GetPropVector(const char[] prop, float vec[3], int element=0);
 
@@ -159,7 +159,7 @@ native void GameRules_GetPropVector(const char[] prop, float vec[3], int element
  * @param vec           Vector to set.
  * @param element       Element # (starting from 0) if property is an array.
  * @param changeState   This parameter is ignored.
- * @error               Not supported.
+ * @error               Prop type is not a vector, or lack of mod support.
  */
 native void GameRules_SetPropVector(const char[] prop, const float vec[3], int element=0, bool changeState=false);
 
@@ -170,7 +170,7 @@ native void GameRules_SetPropVector(const char[] prop, const float vec[3], int e
  * @param buffer        Destination string buffer.
  * @param maxlen        Maximum length of output string buffer.
  * @return              Number of non-null bytes written.
- * @error               Not supported.
+ * @error               Prop type is not a string, or lack of mod support.
  */
 native int GameRules_GetPropString(const char[] prop, char[] buffer, int maxlen);
 
@@ -181,7 +181,7 @@ native int GameRules_GetPropString(const char[] prop, char[] buffer, int maxlen)
  * @param buffer        String to set.
  * @param changeState   This parameter is ignored.
  * @return              Number of non-null bytes written.
- * @error               Not supported.
+ * @error               Prop type is not a string, or lack of mod support.
  */
 native int GameRules_SetPropString(const char[] prop, const char[] buffer, bool changeState=false);
 
diff --git a/plugins/include/sdktools_sound.inc b/plugins/include/sdktools_sound.inc
index 83c622bd..eb816821 100644
--- a/plugins/include/sdktools_sound.inc
+++ b/plugins/include/sdktools_sound.inc
@@ -199,7 +199,7 @@ native void StopSound(int entity, int channel, const char[] name);
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
  * @param ...           Optional list of Float[3] arrays to specify additional origins.
- * @error               Invalid client index.
+ * @error               Invalid client index or client not in game.
  */
 native void EmitSound(const int[] clients,
 				 int numClients,
@@ -238,7 +238,7 @@ native void EmitSound(const int[] clients,
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
  * @param ...           Optional list of Float[3] arrays to specify additional origins.
- * @error               Invalid client index.
+ * @error               Invalid client index, client not in game, or lack of mod support.
  */
 native void EmitSoundEntry(const int[] clients,
 				 int numClients,
@@ -276,7 +276,7 @@ native void EmitSoundEntry(const int[] clients,
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
  * @param ...           Optional list of Float[3] arrays to specify additional origins.
- * @error               Invalid client index.
+ * @error               Invalid client index or client not in game.
  */
 native void EmitSentence(const int[] clients,
 				 int numClients,
@@ -410,7 +410,7 @@ native void RemoveNormalSoundHook(NormalSHook hook);
  * @param dir           Sound direction.
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
- * @error               Invalid client index.
+ * @error               Invalid client index or client not in game.
  */
 stock void EmitSoundToClient(int client,
 				 const char[] sample,
@@ -549,7 +549,7 @@ native bool GetGameSoundParams(const char[] gameSound,
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
  * @return              True if the sound was played successfully, false if it failed
- * @error               Invalid client index.
+ * @error               Invalid client index or client not in game.
  */
 stock bool EmitGameSound(const int[] clients,
 				int numClients,
@@ -631,7 +631,7 @@ stock bool EmitAmbientGameSound(const char[] gameSound,
  * @param dir           Sound direction.
  * @param updatePos     Unknown (updates positions?)
  * @param soundtime     Alternate time to play sound for.
- * @error               Invalid client index.
+ * @error               Invalid client index or client not in game.
  */
 stock bool EmitGameSoundToClient(int client,
 				const char[] gameSound,
diff --git a/plugins/include/sdktools_stringtables.inc b/plugins/include/sdktools_stringtables.inc
index 85372119..500184f6 100644
--- a/plugins/include/sdktools_stringtables.inc
+++ b/plugins/include/sdktools_stringtables.inc
@@ -146,6 +146,7 @@ native void SetStringTableData(int tableidx, int stringidx, const char[] userdat
  * @param length        Length of user data string. This should include the null terminator.
  *                      If set to -1, then user data will be not be altered if the specified string
  *                      already exists in the string table.
+ * @error               Invalid string table index.
  */
 native void AddToStringTable(int tableidx, const char[] str, const char[] userdata="", int length=-1);
 
diff --git a/plugins/include/sdktools_trace.inc b/plugins/include/sdktools_trace.inc
index 3ec07259..865f633d 100644
--- a/plugins/include/sdktools_trace.inc
+++ b/plugins/include/sdktools_trace.inc
@@ -220,6 +220,7 @@ native int TR_GetPointContents(const float pos[3], int &entindex=-1);
  * @param entindex      Entity index to test.
  * @param pos           World position.
  * @return              Contents mask.
+ * @error               Invalid entity.
  */
 native int TR_GetPointContentsEnt(int entindex, const float pos[3]);
 
@@ -397,6 +398,7 @@ native void TR_TraceHullFilter(const float pos[3],
  * @param flags         Trace flags.
  * @param rtype         Method to calculate the ray direction.
  * @param entity        Entity to clip to.
+ * @error               Invalid entity.
  */
 native void TR_ClipRayToEntity(const float pos[3],
                                const float vec[3],
@@ -413,6 +415,7 @@ native void TR_ClipRayToEntity(const float pos[3],
  * @param maxs          Hull maximum size.
  * @param flags         Trace flags.
  * @param entity        Entity to clip to.
+ * @error               Invalid entity.
  */
 native void TR_ClipRayHullToEntity(const float pos[3],
                                    const float vec[3],
@@ -426,6 +429,7 @@ native void TR_ClipRayHullToEntity(const float pos[3],
  *
  * @param flags         Trace flags.
  * @param entity        Entity to clip to.
+ * @error               Invalid entity.
  */
 native void TR_ClipCurrentRayToEntity(int flags, int entity);
 
@@ -517,6 +521,7 @@ native Handle TR_TraceHullFilterEx(const float pos[3],
  * @param rtype         Method to calculate the ray direction.
  * @param entity        Entity to clip to.
  * @return              Ray trace handle, which must be closed via CloseHandle().
+ * @error               Invalid entity.
  */
 native Handle TR_ClipRayToEntityEx(const float pos[3],
                                    const float vec[3],
@@ -534,6 +539,7 @@ native Handle TR_ClipRayToEntityEx(const float pos[3],
  * @param flags         Trace flags.
  * @param entity        Entity to clip to.
  * @return              Ray trace handle, which must be closed via CloseHandle().
+ * @error               Invalid entity.
  */
 native Handle TR_ClipRayHullToEntityEx(const float pos[3],
                                        const float vec[3],
@@ -548,6 +554,7 @@ native Handle TR_ClipRayHullToEntityEx(const float pos[3],
  * @param flags         Trace flags.
  * @param entity        Entity to clip to.
  * @return              Ray trace handle, which must be closed via CloseHandle().
+ * @error               Invalid entity.
  */
 native Handle TR_ClipCurrentRayToEntityEx(int flags, int entity);
 
diff --git a/plugins/include/sdktools_voice.inc b/plugins/include/sdktools_voice.inc
index e2e76fa3..7249ec67 100644
--- a/plugins/include/sdktools_voice.inc
+++ b/plugins/include/sdktools_voice.inc
@@ -75,6 +75,7 @@ forward void OnClientSpeakingEnd(int client);
  *
  * @param client        The client index
  * @param flags         The voice flags
+ * @error               Invalid client index or client not connected.
  */
 native void SetClientListeningFlags(int client, int flags);
 
@@ -83,6 +84,7 @@ native void SetClientListeningFlags(int client, int flags);
  *
  * @param client        The client index
  * @return              The current voice flags
+ * @error               Invalid client index or client not connected.
  */
 native int GetClientListeningFlags(int client);
 
@@ -116,6 +118,7 @@ native bool GetClientListening(int iReceiver, int iSender);
  * @param iSender       The sender index.
  * @param override      The override of the receiver's ability to listen to the sender.
  * @return              True if successful otherwise false.
+ * @error               Listener or sender client index is invalid or not connected.
  */
 native bool SetListenOverride(int iReceiver, int iSender, ListenOverride override);
 
@@ -125,6 +128,7 @@ native bool SetListenOverride(int iReceiver, int iSender, ListenOverride overrid
  * @param iReceiver     The listener index.
  * @param iSender       The sender index.
  * @return              The override value.
+ * @error               Listener or sender client index is invalid or not connected.
  */
 native ListenOverride GetListenOverride(int iReceiver, int iSender);
 
@@ -134,5 +138,6 @@ native ListenOverride GetListenOverride(int iReceiver, int iSender);
  * @param iMuter        The muter index.
  * @param iMutee        The mutee index.
  * @return              True if muter has muted mutee, false otherwise.
+ * @error               Muter or mutee client index is invalid or not connected.
  */
 native bool IsClientMuted(int iMuter, int iMutee);
diff --git a/plugins/include/sourcemod.inc b/plugins/include/sourcemod.inc
index 9a78763c..8b219200 100644
--- a/plugins/include/sourcemod.inc
+++ b/plugins/include/sourcemod.inc
@@ -691,6 +691,7 @@ enum Address
  * @param size          How many bytes should be read.
  *                      If loading a floating-point value, use NumberType_Int32.
  * @return              The value that is stored at that address.
+ * @error               Address is null or pointing to reserved memory.
  */
 native any LoadFromAddress(Address addr, NumberType size);
 
@@ -701,6 +702,7 @@ native any LoadFromAddress(Address addr, NumberType size);
  * @param data          Value to store at the address.
  * @param size          How many bytes should be written.
  *                      If storing a floating-point value, use NumberType_Int32.
+ * @error               Address is null or pointing to reserved memory.
  */
 native void StoreToAddress(Address addr, any data, NumberType size);
 
diff --git a/plugins/include/string.inc b/plugins/include/string.inc
index 6fe84f32..6f3f0dd3 100644
--- a/plugins/include/string.inc
+++ b/plugins/include/string.inc
@@ -172,6 +172,7 @@ native int FormatEx(char[] buffer, int maxlength, const char[] format, any ...);
  * @param varpos        Argument number which contains the '...' symbol.
  *                      Note: Arguments start at 1.
  * @return              Number of bytes written.
+ * @error               Invalid argument index.
  */
 native int VFormat(char[] buffer, int maxlength, const char[] format, int varpos);
 
@@ -286,6 +287,7 @@ native int SplitString(const char[] source, const char[] split, char[] part, int
  * @param replace       String to replace the search string with.
  * @param caseSensitive If true (default), search is case sensitive.
  * @return              Number of replacements that were performed.
+ * @error               'search' parameter is empty.
  */
 native int ReplaceString(char[] text, int maxlength, const char[] search, const char[] replace, bool caseSensitive=true);
 
@@ -305,6 +307,7 @@ native int ReplaceString(char[] text, int maxlength, const char[] search, const
  * @return              Index into the buffer (relative to the start) from where
  *                      the last replacement ended, or -1 if no replacements were
  *                      made.
+ * @error               'search' parameter is empty.
  */
 native int ReplaceStringEx(char[] text, int maxlength, const char[] search, const char[] replace, int searchLen=-1, int replaceLen=-1, bool caseSensitive=true);
 
diff --git a/plugins/include/timers.inc b/plugins/include/timers.inc
index 97eda41c..2a081302 100644
--- a/plugins/include/timers.inc
+++ b/plugins/include/timers.inc
@@ -95,7 +95,7 @@ native Handle CreateTimer(float interval, Timer func, any data=INVALID_HANDLE, i
  * @param timer         Timer Handle to kill.
  * @param autoClose     If autoClose is true, the data that was passed to CreateTimer() will
  *                      be closed as a handle if TIMER_DATA_HNDL_CLOSE was not specified.
- * @error               Invalid handles will cause a run time error.
+ * @error               Invalid timer handle.
  */
 native void KillTimer(Handle timer, bool autoClose=false);
 
@@ -105,6 +105,7 @@ native void KillTimer(Handle timer, bool autoClose=false);
  * @param timer         Timer Handle to trigger.
  * @param reset         If reset is true, the elapsed time counter is reset
  *                      so the full interval must pass again.
+ * @error               Invalid timer handle.
  */
 native void TriggerTimer(Handle timer, bool reset=false);
 
diff --git a/plugins/include/topmenus.inc b/plugins/include/topmenus.inc
index c406cb4d..abdddc33 100644
--- a/plugins/include/topmenus.inc
+++ b/plugins/include/topmenus.inc
@@ -361,7 +361,7 @@ native void RemoveFromTopMenu(Handle topmenu, TopMenuObject topobj);
  * @param client        Client index.
  * @param position      Position to display from.
  * @return              True on success, false on failure.
- * @error               Invalid TopMenu Handle or client not in game.
+ * @error               Invalid TopMenu Handle, invalid client index, or client not in game.
  */
 native bool DisplayTopMenu(Handle topmenu, int client, TopMenuPosition position);
 
@@ -372,7 +372,7 @@ native bool DisplayTopMenu(Handle topmenu, int client, TopMenuPosition position)
  * @param category      Category topobj id.
  * @param client        Client index.
  * @return              True on success, false on failure.
- * @error               Invalid TopMenu Handle or client not in game.
+ * @error               Invalid TopMenu Handle, invalid client index, or client not in game.
  */
 native bool DisplayTopMenuCategory(Handle topmenu, TopMenuObject category, int client);