Update dhooks.inc documentation for consistency (#1658)

* Update dhooks.inc documentation for consistency

- Modifies whitespace (change tabs to spaces for non initial indents, fix alignments, create consistency with rest of SM docs)
- Change `/*` to `/**` for consistency and to indicate comment doc
- Removes incorrect `@noreturn` doc

* Split long comments across multiple lines

* Remove `@noreturn` in IGameConfigs.h

* Remove `@noreturn` from IGameHelpers.h

* Remove `@noreturn` from asm.c

* Add `@noreturn` to ThrowError

* Add `@noreturn` and `@error` to ThrowNativeError

plugins/include/dhooks.inc

@@ -119,18 +119,18 @@ enum CallingConvention
 
 enum HookMode
 {
-	Hook_Pre,                   // Callback will be executed BEFORE the original function.
+	Hook_Pre,                   /**< Callback will be executed BEFORE the original function. */
-	Hook_Post                   // Callback will be executed AFTER the original function.
+	Hook_Post                   /**< Callback will be executed AFTER the original function. */
 };
 
 enum MRESReturn
 {
-	MRES_ChangedHandled = -2,	// Use changed values and return MRES_Handled
+	MRES_ChangedHandled = -2,   /**< Use changed values and return MRES_Handled */
-	MRES_ChangedOverride,		// Use changed values and return MRES_Override
+	MRES_ChangedOverride,       /**< Use changed values and return MRES_Override */
-	MRES_Ignored,				// plugin didn't take any action
+	MRES_Ignored,               /**< plugin didn't take any action */
-	MRES_Handled,				// plugin did something, but real function should still be called
+	MRES_Handled,               /**< plugin did something, but real function should still be called */
-	MRES_Override,				// call real function, but use my return value
+	MRES_Override,              /**< call real function, but use my return value */
-	MRES_Supercede				// skip real function; use my return value
+	MRES_Supercede              /**< skip real function; use my return value */
 };
 
 enum DHookPassFlag
@@ -194,6 +194,7 @@ typeset DHookRemovalCB
 {
 	function void (int hookid);
 };
+
 typeset DHookCallback
 {
 	// Function Example: void Ham::Test() with this pointer ignore
@@ -368,16 +369,17 @@ methodmap DHookParam < Handle
 	//
 	// @param num           Parameter number to check, starting at 1.
 	//
-	// @return              True if null, false otherwise.
+	// @return              true if null, false otherwise.
 	// @error               Non-pointer parameter.
 	public native bool IsNull(int num);
 
 	// Get param address (Use only for ptr param types)
 	//
-	// @param num			Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
+	// @param num           Param number to get. (Example if the function has 2 params and you need the value
+	//                      of the first param num would be 1.)
 	//
+	// @return              Address of the parameter.
 	// @error               Invalid handle. Invalid param number. Invalid param type.
-	// @return address of the parameter.
 	public native Address GetAddress(int num);
 };
 
@@ -449,7 +451,7 @@ methodmap DHookSetup < Handle
 	// @param source        Whether to look in Offsets, Signatures, or Addresses.
 	// @param name          Name of the property to find.
 	//
-	// @return              True on success, false if nothing was found.
+	// @return              true on success, false if nothing was found.
 	// @error               Invalid setup or gamedata handle.
 	public native bool SetFromConf(Handle gameconf, SDKFuncConfSource source, const char[] name);
 
@@ -549,7 +551,7 @@ methodmap DynamicHook < DHookSetup
 	//
 	// @param hookid        Hook id to remove.
 	//
-	// @return              True on success, false otherwise
+	// @return              true on success, false otherwise
 	public static native bool RemoveHook(int hookid);
 };
 
@@ -600,7 +602,7 @@ methodmap DynamicDetour < DHookSetup
 	//                        You can access the parameters and get/set the return value.
 	// @param callback      Callback function.
 	//
-	// @return              True if detour was enabled, false otherwise.
+	// @return              true if detour was enabled, false otherwise.
 	// @error               Hook handle is not setup for a detour.
 	public native bool Enable(HookMode mode, DHookCallback callback);
 
@@ -609,30 +611,31 @@ methodmap DynamicDetour < DHookSetup
 	// @param mode          The hook mode to disable - pre or post.
 	// @param callback      Callback function.
 	//
-	// @return              True if detour was disabled, false otherwise.
+	// @return              true if detour was disabled, false otherwise.
 	// @error               Hook handle is not setup for a detour or function is not detoured.
 	public native bool Disable(HookMode mode, DHookCallback callback);
 };
 
-/* Adds an entity listener hook
+/**
+ * Adds an entity listener hook
  *
  * @param type              Type of listener to add
  * @param callback          Callback to use
- *
- * @noreturn
  */
 native void DHookAddEntityListener(ListenType type, ListenCB callback);
 
-/* Removes an entity listener hook
+/**
+ * Removes an entity listener hook
  *
  * @param type              Type of listener to remove
  * @param callback          Callback this listener was using
  *
- * @return True if one was removed false otherwise.
+ * @return                  true if one was removed, false otherwise
  */
 native bool DHookRemoveEntityListener(ListenType type, ListenCB callback);
 
-/* Creates a hook
+/**
+ * Creates a hook
  *
  * @param offset            vtable offset of function to hook
  * @param hooktype          Type of hook
@@ -666,7 +669,8 @@ native DynamicDetour DHookCreateDetour(Address funcaddr, CallingConvention callC
  * @param name              Name of the function in the gamedata to load.
  *
  * @return                  Setup handle for the detour or INVALID_HANDLE if offset/signature/address wasn't found.
- * @error				Failed to create detour setup handle, invalid gamedata handle, invalid callback function or failed to find function in gamedata.
+ * @error                   Failed to create detour setup handle, invalid gamedata handle, invalid callback function or
+ *                          failed to find function in gamedata.
  */
 native DHookSetup DHookCreateFromConf(Handle gameconf, const char[] name);
 
@@ -678,7 +682,7 @@ native DHookSetup DHookCreateFromConf(Handle gameconf, const char[] name);
  * @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.
+ * @return                  true on success, false if nothing was found.
  * @error                   Invalid setup or gamedata handle.
  */
 native bool DHookSetFromConf(Handle setup, Handle gameconf, SDKFuncConfSource source, const char[] name);
@@ -687,10 +691,11 @@ native bool DHookSetFromConf(Handle setup, Handle gameconf, SDKFuncConfSource so
  * Enable the detour of the function described in the hook setup handle.
  *
  * @param setup             Hook setup handle
- * @param post			True to make the hook a post hook. (If you need to change the retunr value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
+ * @param post              true to make the hook a post hook. (If you need to change the return value or need the return
+ *                          value use a post hook! If you need to change params and return use a pre and post hook!)
  * @param callback          Callback function
  *
- * @return				True if detour was enabled, false otherwise.
+ * @return                  true if detour was enabled, false otherwise.
  * @error                   Hook handle is not setup for a detour.
  */
 native bool DHookEnableDetour(Handle setup, bool post, DHookCallback callback);
@@ -699,15 +704,16 @@ native bool DHookEnableDetour(Handle setup, bool post, DHookCallback callback);
  * Disable the detour of the function described in the hook setup handle.
  *
  * @param setup             Hook setup handle
- * @param post			True to disable a post hook.
+ * @param post              true to disable a post hook.
  * @param callback          Callback function
  *
- * @return				True if detour was disabled, false otherwise.
+ * @return                  true if detour was disabled, false otherwise.
  * @error                   Hook handle is not setup for a detour or function is not detoured.
  */
 native bool DHookDisableDetour(Handle setup, bool post, DHookCallback callback);
 
-/* Adds param to a hook setup
+/**
+ * Adds param to a hook setup
  *
  * @param setup             Setup handle to add the param to.
  * @param type              Param type
@@ -716,124 +722,141 @@ native bool DHookDisableDetour(Handle setup, bool post, DHookCallback callback);
  * @param custom_register   The register this argument is passed in instead of the stack.
  *
  * @error                   Invalid setup handle or too many params added (request upping the max in thread)
- * @noreturn
  */
 native void DHookAddParam(Handle setup, HookParamType type, int size=-1, DHookPassFlag flag=DHookPass_ByVal, DHookRegister custom_register=DHookRegister_Default);
 
-/* Hook entity
+/**
+ * Hook entity
  *
  * @param setup             Setup handle to use to add the hook.
- * @param post			True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
+ * @param post              true to make the hook a post hook. (If you need to change the return value or need the return
+ *                          value use a post hook! If you need to change params and return use a pre and post hook!)
  * @param entity            Entity index to hook on.
- * @param removalcb		Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and will call this callback)
+ * @param removalcb         Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and
+ *                          will call this callback)
  * @param callback          Optional callback function, if not set here must be set when creating the hook.
  *
- * @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
  * @return                  INVALID_HOOK_ID on fail a hookid on success
+ * @error                   Invalid setup handle, invalid address, invalid hook type or invalid callback.
  */
 native int DHookEntity(Handle setup, bool post, int entity, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
 
-/* Hook gamerules
+/**
+ * Hook gamerules
  *
  * @param setup             Setup handle to use to add the hook.
- * @param post			True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
+ * @param post              true to make the hook a post hook. (If you need to change the return value or need the return
- * @param removalcb		Callback for when the hook is removed (Game rules hooks are auto-removed on map end and will call this callback)
+ *                          value use a post hook! If you need to change params and return use a pre and post hook!)
+ * @param removalcb         Callback for when the hook is removed (Game rules hooks are auto-removed on map end and will
+ *                          call this callback)
  * @param callback          Optional callback function, if not set here must be set when creating the hook.
  *
- * @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
  * @return                  INVALID_HOOK_ID on fail a hookid on success
+ * @error                   Invalid setup handle, invalid address, invalid hook type or invalid callback.
  */
 native int DHookGamerules(Handle setup, bool post, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
 
-/* Hook a raw pointer
+/**
+ * Hook a raw pointer
  *
  * @param setup             Setup handle to use to add the hook.
- * @param post			True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
+ * @param post              true to make the hook a post hook. (If you need to change the return value or need the return 
+ *                          alue use a post hook! If you need to change params and return use a pre and post hook!)
  * @param addr              This pointer address.
- * @param removalcb		Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and will call this callback)
+ * @param removalcb         Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and
+ *                          will call this callback)
  * @param callback          Optional callback function, if not set here must be set when creating the hook.
  *
- * @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
  * @return                  INVALID_HOOK_ID on fail a hookid on success
+ * @error                   Invalid setup handle, invalid address, invalid hook type or invalid callback.
  */
 native int DHookRaw(Handle setup, bool post, Address addr, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
 
-/* Remove hook by hook id
+/**
+ * Remove hook by hook id
  *
  * @param hookid            Hook id to remove
  *
- * @return true on success false otherwise
+ * @return                  true on success, false otherwise
  * @note                    This will not fire the removal callback!
  */
 native bool DHookRemoveHookID(int hookid);
 
-/* Get param value (Use only for: int, entity, bool or float param types)
+/**
+ * Get param value (Use only for: int, entity, bool or float param types)
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1. 0 Will return the number of params stored)
+ * @param num               Param number to get. (Example if the function has 2 params and you need the value of the first
+ *                          param num would be 1. 0 Will return the number of params stored)
  *
- * @error Invalid handle. Invalid param number. Invalid param type.
  * @return                  value if num greater than 0. If 0 returns paramcount.
+ * @error                   Invalid handle. Invalid param number. Invalid param type.
  */
 native any DHookGetParam(Handle hParams, int num);
 
-/* Get vector param value
+/**
+ * Get vector param value
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
+ * @param num               Param number to get. (Example if the function has 2 params and you need the value of the first
+ *                          param num would be 1.)
  * @param vec               Vector buffer to store result.
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @noreturn
  */
 native void DHookGetParamVector(Handle hParams, int num, float vec[3]);
 
-/* Get string param value
+/**
+ * Get string param value
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
+ * @param num               Param number to get. (Example if the function has 2 params and you need the value of the first
+ *                          param num would be 1.)
  * @param buffer            String buffer to store result
  * @param size              Buffer size
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @noreturn
  */
 native void DHookGetParamString(Handle hParams, int num, char[] buffer, int size);
 
-/* Set param value (Use only for: int, entity, bool or float param types)
+/**
+ * Set param value (Use only for: int, entity, bool or float param types)
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
+ * @param num               Param number to set (Example if the function has 2 params and you need to set the value of the
+ *                          first param num would be 1.)
  * @param value             Value to set it as (only pass int, bool, float or entity index)
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @noreturn
  */
 native void DHookSetParam(Handle hParams, int num, any value);
 
-/* Set vector param value
+/**
+ * Set vector param value
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
+ * @param num               Param number to set (Example if the function has 2 params and you need to set the value of the
+ *                          first param num would be 1.)
  * @param vec               Value to set vector as.
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @noreturn
  */
 native void DHookSetParamVector(Handle hParams, int num, float vec[3]);
 
-/* Set string param value
+/**
+ * Set string param value
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
+ * @param num               Param number to set (Example if the function has 2 params and you need to set the value of the
+ *                          first param num would be 1.)
  * @param value             Value to set string as.
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @noreturn
  */
 native void DHookSetParamString(Handle hParams, int num, char[] value);
 
-/* Get return value (Use only for: int, entity, bool or float return types)
+/**
+ * Get return value (Use only for: int, entity, bool or float return types)
  *
  * @param hReturn           Handle to return structure
  *
@@ -842,60 +865,61 @@ native void DHookSetParamString(Handle hParams, int num, char[] value);
  */
 native any DHookGetReturn(Handle hReturn);
 
-/* Get return vector value
+/**
+ * Get return vector value
  *
  * @param hReturn           Handle to return structure
  * @param vec               Vector buffer to store result in. (In pre hooks will be default value (0.0,0.0,0.0))
  *
  * @error                   Invalid Handle, invalid type.
- * @noreturn
  */
 native void DHookGetReturnVector(Handle hReturn, float vec[3]);
 
-/* Get return string value
+/**
+ * Get return string value
  *
  * @param hReturn           Handle to return structure
  * @param buffer            String buffer to store result in. (In pre hooks will be default value "")
  * @param size              String buffer size
  *
  * @error                   Invalid Handle, invalid type.
- * @noreturn
  */
 native void DHookGetReturnString(Handle hReturn, char[] buffer, int size);
 
-/* Set return value (Use only for: int, entity, bool or float return types)
+/**
+ * Set return value (Use only for: int, entity, bool or float return types)
  *
  * @param hReturn           Handle to return structure
  * @param value             Value to set return as
  *
  * @error                   Invalid Handle, invalid type.
- * @noreturn
  */
 native void DHookSetReturn(Handle hReturn, any value);
 
-/* Set return vector value
+/**
+ * Set return vector value
  *
  * @param hReturn           Handle to return structure
  * @param vec               Value to set return vector as
  *
  * @error                   Invalid Handle, invalid type.
- * @noreturn
  */
 native void DHookSetReturnVector(Handle hReturn, float vec[3]);
 
-/* Set return string value
+/**
+ * Set return string value
  *
  * @param hReturn           Handle to return structure
  * @param value             Value to set return string as
  *
  * @error                   Invalid Handle, invalid type.
- * @noreturn
  */
 native void DHookSetReturnString(Handle hReturn, char[] value);
 
 //WE SHOULD WRAP THESE AROUND STOCKS FOR NON PTR AS WE SUPPORT BOTH WITH THESE NATIVE'S
 
-/* Gets an objects variable value
+/**
+ * Gets an objects variable value
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to get.
@@ -907,7 +931,8 @@ native void DHookSetReturnString(Handle hReturn, char[] value);
  */
 native any DHookGetParamObjectPtrVar(Handle hParams, int num, int offset, ObjectValueType type);
 
-/* Sets an objects variable value
+/**
+ * Sets an objects variable value
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to set.
@@ -916,11 +941,11 @@ native any DHookGetParamObjectPtrVar(Handle hParams, int num, int offset, Object
  * @param value             The value to set the var to.
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
- * @noreturn
  */
 native void DHookSetParamObjectPtrVar(Handle hParams, int num, int offset, ObjectValueType type, any value);
 
-/* Gets an objects vector variable value
+/**
+ * Gets an objects vector variable value
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to get.
@@ -929,11 +954,11 @@ native void DHookSetParamObjectPtrVar(Handle hParams, int num, int offset, Objec
  * @param buffer            Buffer to store the result vector
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
- * @noreturn
  */
 native void DHookGetParamObjectPtrVarVector(Handle hParams, int num, int offset, ObjectValueType type, float buffer[3]);
 
-/* Sets an objects vector variable value
+/**
+ * Sets an objects vector variable value
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to set.
@@ -942,11 +967,11 @@ native void DHookGetParamObjectPtrVarVector(Handle hParams, int num, int offset,
  * @param value             The value to set the vector var to.
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
- * @noreturn
  */
 native void DHookSetParamObjectPtrVarVector(Handle hParams, int num, int offset, ObjectValueType type, float value[3]);
 
-/* Gets an objects string variable value
+/**
+ * Gets an objects string variable value
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to get.
@@ -956,27 +981,29 @@ native void DHookSetParamObjectPtrVarVector(Handle hParams, int num, int offset,
  * @param size              Size of the buffer
  *
  * @error                   Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
- * @noreturn
  */
 native void DHookGetParamObjectPtrString(Handle hParams, int num, int offset, ObjectValueType type, char[] buffer, int size);
 
-/* Checks if a pointer param is null
+/**
+ * Checks if a pointer param is null
  *
  * @param hParams           Handle to params structure
  * @param num               Param number to check.
  *
+ * @return                  true if null, false otherwise.
  * @error                   Non pointer param
- * @return True if null false otherwise.
  */
 native bool DHookIsNullParam(Handle hParams, int num);
 
-/* Get param address (Use only for ptr param types)
+/**
+ * Get param address (Use only for ptr param types)
  *
  * @param hParams           Handle to params structure
- * @param num			Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
+ * @param num               Param number to get. (Example if the function has 2 params and you need the value of the first
+ *                          param num would be 1.)
  * 
+ * @return                  Address of the parameter.
  * @error                   Invalid handle. Invalid param number. Invalid param type.
- * @return address of the parameter.
  */
 native Address DHookGetParamAddress(Handle hParams, int num);
 

plugins/include/functions.inc

@@ -466,6 +466,8 @@ native void CreateNative(const char[] name, NativeCall func);
  * @param error         Error code to use.
  * @param fmt           Error message format.
  * @param ...           Format arguments.
+ * @noreturn
+ * @error               Always!
  */
 native int ThrowNativeError(int error, const char[] fmt, any ...);
 

plugins/include/sourcemod.inc

@@ -348,6 +348,7 @@ native void SetFailState(const char[] string, any ...);
  *
  * @param fmt           String format.
  * @param ...           Format arguments.
+ * @noreturn
  * @error               Always!
  */
 native void ThrowError(const char[] fmt, any ...);

public/IGameConfigs.h

@@ -158,7 +158,6 @@ namespace SourceMod
 		 *
 		 * @param sectionname	Section name to hook.
 		 * @param listener		Listener callback.
-		 * @noreturn
 		 */
 		virtual void AddUserConfigHook(const char *sectionname, ITextListener_SMC *listener) =0;
 
@@ -167,7 +166,6 @@ namespace SourceMod
 		 *
 		 * @param sectionname	Section name to unhook.
 		 * @param listener		Listener callback.
-		 * @noreturn
 		 */
 		virtual void RemoveUserConfigHook(const char *sectionname, ITextListener_SMC *listener) =0;
 

public/IGameHelpers.h

@@ -188,7 +188,6 @@ namespace SourceMod
 		 *
 		 * @param hndl			CBaseHandle object.
 		 * @param pEnt			Edict pointer.
-		 * @noreturn
 		 */
 		virtual void SetHandleEntity(CBaseHandle &hndl, edict_t *pEnt) =0;
 

public/asm/asm.c

@@ -24,7 +24,6 @@
 *
 * @param dest		Destination buffer where a call opcode + addr (5 bytes) has just been written.
 * @param pc		The program counter value that needs to be set (usually the next address from the source).
-* @noreturn
 */
 void check_thunks(unsigned char *dest, unsigned char *pc)
 {