docs: overhaul Pawn include documentation

reapi/extra/amxmodx/scripting/include/reapi.inc

@@ -124,7 +124,8 @@ enum
                      // @note Warning: Be very careful, using this type of return will skip calls for all following AMXX plugins
 
 	HC_BYPASS        // Skip calls for all following AMXX plugins, but call the original function
-                     // @note Warning: In PRE skips all forwards including POST forwards
+                     // @note Warning: Applies to void hookchains only: in PRE skips all forwards including POST forwards.
+                     // @note          For hookchains with a return value, HC_BYPASS acts like HC_CONTINUE.
 };
 
 /**
@@ -166,6 +167,7 @@ native HookChain:RegisterHookChain(ReAPIFunc:function_id, const callback[], post
 *
 * @param hook       The hook to stop
 *
+* @return           Returns true if the hook is successfully disabled, otherwise false
 */
 native bool:DisableHookChain(HookChain:hook);
 
@@ -185,6 +187,9 @@ native bool:EnableHookChain(HookChain:hook);
 * @param type       To specify the ATYPE_* parameter, look at the enum AType
 * @param value      The value to set the return to
 *
+* @return           Returns true on success, otherwise false
+*
+* @error            The type must exactly match the return type registered for the hook; ATYPE_TRACE is not supported.
 */
 native SetHookChainReturn(AType:type, any:...);
 
@@ -193,19 +198,20 @@ native SetHookChainReturn(AType:type, any:...);
 * This has no effect in pre hookchain.
 *
 * @param type       To specify the ATYPE_* parameter, look at the enum AType
-* @param [maxlen]   Max length of string (optional)
+* @param maxlen    Max length of string (required when type is ATYPE_STRING)
 *
-* @return           If an integer or boolean or one byte or float, array or everything else is passed via 1st argument and more
+* @return           Returns the hookchain return value (see SetHookChainReturn)
 */
 native any:GetHookChainReturn(AType:type, any:...);
 
 /*
 * Set hookchain argument.
-* This has no effect in post hookchain.
+* In post hookchain this does not affect the original function (it has already been called),
+* but subsequent post forwards will see the changed value.
 *
 * @param number     Number of argument
+* @param type       To specify the ATYPE_* parameter, look at the enum AType
 * @param value      New value
-* @param [maxlen]   Max length of string (optional)
 *
 * @return           Returns true if the function is successfully executed, otherwise false
 */
@@ -241,13 +247,13 @@ native bool:FClassnameIs(const entityIndex, const className[]);
 *
 * @param entity     Grenade entity
 *
-* @return           return enum's of WeaponIdType
+* @return           WeaponIdType enum value
 */
 native WeaponIdType:GetGrenadeType(const entityIndex);
 
 /*
 * Sets the view entity on a client.
-* This allows pfnSetView able to hooks.
+* This allows pfnSetView to be hooked.
 *
 * @param index       Client index
 * @param viewEntity  Entity index
@@ -256,10 +262,11 @@ native WeaponIdType:GetGrenadeType(const entityIndex);
 native engset_view(const index, const viewEntity);
 
 /*
-* Gets the return index of the current view entity on a client.
+* Gets the index of the current view entity on a client.
 *
 * @param index  Client index
 *
+* @return       View entity index, 0 if none
 */
 native get_viewent(const index);
 

reapi/extra/amxmodx/scripting/include/reapi_engine.inc

@@ -25,27 +25,32 @@ native any:get_entvar(const index, const EntVars:var, any:...);
 native set_ucmd(const ucmd, const UCmd:var, any:...);
 
 /*
-* Returns usercmd data from an entity.
+* Returns usercmd data from a usercmd structure handle (see get_pmove(pm_cmd)).
 * Use the ucmd_* UCmd enum
 */
 native any:get_ucmd(const ucmd, const UCmd:var, any:...);
 
 /*
 * Sets netchan data.
 * Use the net_* NetChan enum
+*
+* @note index must be a connected client
 */
 native set_netchan(const index, const NetChan:var, any:...);
 
 /*
-* Returns metchan data from an client.
+* Returns netchan data from a client.
 * Use the net_* NetChan enum
+*
+* @note index must be a connected client
 */
 native any:get_netchan(const index, const NetChan:var, any:...);
 
 /*
 * Sets a NetAdr var.
 *
-* @param var        The specified mvar, look at the enum NetAdrVars
+* @param adr        Pointer/handle to a netadr structure (e.g. obtained via get_netchan(index, net_remote_address))
+* @param var        NetAdrVars member to set, look at the enum NetAdrVars
 *
 * @return           1 on success.
 */
@@ -54,9 +59,10 @@ native set_netadr(const adr, const NetAdrVars:var, any:...);
 /*
 * Returns a NetAdr var
 *
-* @param var        The specified mvar, look at the enum NetAdrVars
+* @param adr        Pointer/handle to a netadr structure (e.g. obtained via get_netchan(index, net_remote_address))
+* @param var        NetAdrVars member to get, look at the enum NetAdrVars
 *
-* @return           If an integer or boolean or one byte, array or everything else is passed via the 3rd argument and more, look at the argument list for the specified mvar
+* @return           If an integer or boolean or one byte, array or everything else is passed via the 3rd argument and more, look at the argument list for the specified member
 */
 native any:get_netadr(const adr, const NetAdrVars:var, any:...);
 
@@ -88,11 +94,11 @@ native set_key_value(const pbuffer, const key[], const value[]);
 /*
 * Gets an AMXX string buffer from a infobuffer pointer
 *
-* @param buffer     Info string pointer
-* @param value      String to copy value to
+* @param pbuffer    Info string pointer
+* @param output     String to copy value to
 * @param maxlen     Maximum size of the output buffer
 *
-* @return           Returns a string buffer on infobuffer pointer
+* @return           Number of cells written to the output buffer
 */
 native get_key_value_buffer(const pbuffer, const output[], const maxlen);
 
@@ -208,7 +214,7 @@ native rh_set_mapname(const mapname[]);
 * @param output     Buffer to copy map name to
 * @param len        Maximum buffer size
 * @param type       MNT_SET will return the name of the current map
-*                   MNT_TRUE will return the original map name independant of the name set with via rh_set_mapname
+*                   MNT_TRUE will return the original map name independent of the name set via rh_set_mapname
 *
 * @noreturn
 */
@@ -260,7 +266,7 @@ native rh_update_user_info(const index);
 native rh_drop_client(const index, const message[] = "");
 
 /*
-* -
+* Returns the address string the most recent connection request came from (net_from).
 *
 * @param output     Buffer to copy the ip address
 * @param len        Maximum buffer size
@@ -275,7 +281,9 @@ native rh_get_net_from(output[], len);
 *
 * @param index      Client index
 *
-* @return           Netchan connection time in seconds or 0 if client index is invalid or client is not connected
+* @return           Netchan connection time in seconds
+*
+* @error            Invalid client index or client is not connected
 */
 native rh_get_client_connect_time(const index);
 
@@ -332,7 +340,7 @@ enum MessageHook
 *
 * @note The callback arguments have:
 *   msg_id          - Message id
-*   msg_dest        - Destination type (see MSG_* constants in messages_const.inc)
+*   msg_dest        - Destination type (see MSG_* constants in message_const.inc)
 *   msg_entity      - Entity receiving the message
 *
 * @note             You can modify the message content using SetMessageData native before the original function is invoked.
@@ -376,7 +384,7 @@ native bool:DisableHookMessage(const MessageHook:handle);
 * Sets the message data in the current game message.
 *
 * @param type       The type of the message data that can be changed
-* @param ...        Additional args depending on the type of the message argument being retrieved (For more details, look at the enum MsgArgType)
+* @param ...        Additional args depending on the type of the message argument being set (For more details, look at the enum MsgArgType)
 *
 * @return           Returns true if the message data is successfully set, otherwise false.
 */
@@ -447,13 +455,14 @@ native MsgBlockType:GetMessageBlock(const msgid);
 * This can be one of the following:
 *                   - MsgAny:      Check if any part of the message has been modified
 *                   - MsgDest:     Check if the destination has been modified
-*                   - MsgIndex:    Check if the message ID has been modified
+*                   - MsgMsgId:    Check if the message ID has been modified
 *                   - MsgOrigin:   Check if the origin has been modified
 *                   - MsgTargetId: Check if the index of the recipient client has been modified
 *                   - MsgArg:      Check if a specific argument of the message has been modified
 *
 * @param number     The number of the argument to check for modification (used only when type is MsgDataType:MsgArg)
-*                   Default value is -1, which means the argument number is not applicable
+*                   Default value is -1; allowed only when type is not MsgArg
+*                   (for MsgArg the argument number is required)
 *
 * @return           Returns true if the specified data type has been modified, false otherwise
 */
@@ -462,11 +471,11 @@ native bool:IsMessageDataModified(MsgDataType:type = MsgAny, const number = -1);
 /**
 * Resets a specific type of message data to its original value
 *
-* @param type       The type of the data to check for modification
+* @param type       The type of the data to reset
 * This can be one of the following:
 *                   - MsgAny:      Reset all modified message data to its original values
 *                   - MsgDest:     Reset the destination to its original value
-*                   - MsgIndex:    Reset the message ID to its original value
+*                   - MsgMsgId:    Reset the message ID to its original value
 *                   - MsgOrigin:   Reset the origin to its original value
 *                   - MsgTargetId: Reset the index of the recipient client to its original value
 *                   - MsgArg:      Reset a specific argument of the message to its original value