cstrike/csx/csstats: Added documentation, consistency updates, typo fixes

plugins/include/csstats.inc

@@ -12,58 +12,263 @@
 #endif
 #define _csstats_included
 
-/* Gets stats from given weapon index. If wpnindex is 0
+/**
-* then the stats are from all weapons. If weapon has not been used function
+ * Retrieves the client's current weapon statistics.
-* returns 0 in other case 1. Fields in stats are:
+ *
-* 0 - kills
+ * @note For a list of default CS weapon ids see the CSW_* constants in
-* 1 - deaths
+ *       amxconst.inc, this function also works on custom weapons.
-* 2 - headshots
+ * @note For a list of possible body hitplaces see the HIT_* constants in
-* 3 - teamkilling
+ *       amxconst.inc
-* 4 - shots
+ * @note The fields in the statistics are:
-* 5 - hits
+ *          0 - Kills
-* 6 - damage
+ *          1 - Deaths
-
+ *          2 - Headshots
-* For body hits fields see amxconst.inc. */
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Weapon id, or 0 to retrieve total statistics across all
+ *                  weapons
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available for the weapon
+ *                  id
+ * @error           If an invalid client index or weapon id is provided, an
+ *                  error will be thrown.
+ */
 native get_user_wstats(index, wpnindex, stats[8], bodyhits[8]);
 
-/* Gets round stats from given weapon index.*/
+/**
+ * Retrieves the client's weapon statistics from the current round.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Weapon id, or 0 to retrieve total statistics across all
+ *                  weapons
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available for the
+ *                  weapon id
+ * @error           If an invalid client index or weapon id is provided, an
+ *                  error will be thrown.
+ */
 native get_user_wrstats(index, wpnindex, stats[8], bodyhits[8]);
 
-/* Gets overall stats which are stored in file on server
+/**
-* and updated on every respawn or user disconnect.
+ * Retrieves the client's weapon statistics from the permanent storage on the
-* Function returns the position in stats by diff. kills to deaths. */
+ * server.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note Player rank is determined by the difference of kills to deaths.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *          7 - Rank
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          Players rank > 0 on success, or 0 if player is not ranked
+ *                  and no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native get_user_stats(index, stats[8], bodyhits[8]);
 
-/* Gets round stats of player. */
+/**
+ * Retrieves the client's statistics from the current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ *
+ * @return          1 on success, 0 if no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native get_user_rstats(index, stats[8], bodyhits[8]);
 
-/* Gets stats with which user have killed/hurt his victim. If victim is 0
+/**
-* then stats are from all victims. If victim has not been hurt, function
+ * Retrieves the client's statistics inflicted upon another client from the
-* returns 0 in other case 1. User stats are reset on his respawn. */
+ * current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param victim    Victim client index, or 0 to retrieve the statistics against
+ *                  all victims
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ * @param wpnname   Optional buffer to copy last used weapon name to
+ * @param len       Maximum buffer size
+ *
+ * @return          1 on success, 0 if no statistics are available against the
+ *                  specified victim
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native get_user_vstats(index, victim, stats[8], bodyhits[8], wpnname[] = "", len = 0);
 
-/* Gets stats with which user have been killed/hurt. If killer is 0
+/**
-* then stats are from all attacks. If killer has not hurt user, function
+ * Retrieves the client's statistics received from another client from the
-* returns 0 in other case 1. User stats are reset on his respawn. */
+ * current round.
+ *
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *
+ * @param index     Client index
+ * @param wpnindex  Attacker client index, or 0 to retrieve the statistics from
+ *                  all attackers
+ * @param stats     Buffer to copy statistics to
+ * @param bodyhits  Buffer to copy body hits to
+ * @param wpnname   Optional buffer to copy last used weapon name to
+ * @param len       Maximum buffer size
+ *
+ * @return          1 on success, 0 if no statistics are available against the
+ *                  specified attacker
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native get_user_astats(index, wpnindex, stats[8], bodyhits[8], wpnname[] = "", len = 0);
 
-/* Resets life, weapon, victims and attackers user stats. */
+/**
+ * Resets the current round weapon, attacker and victim statistics.
+ *
+ * @param index     Client index
+ *
+ * @noreturn
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
+ */
 native reset_user_wstats(index);
 
-/* Gets overall stats which stored in stats.dat file in amx folder
+/**
-* and updated on every mapchange or user disconnect.
+ * Retrieves statistics from the permanent storage on the server via iterative,
-* Function returns next index of stats entry or 0 if no more exists. */
+ * incremental access.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note Player rank is determined by the difference of kills to deaths.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ * @note The fields in the statistics are:
+ *          0 - Kills
+ *          1 - Deaths
+ *          2 - Headshots
+ *          3 - Teamkills
+ *          4 - Shots
+ *          5 - Hits
+ *          6 - Damage
+ *          7 - Rank
+ *
+ * @param index         Rank index
+ * @param stats         Buffer to copy statistics to
+ * @param bodyhits      Buffer to copy body hits to
+ * @param name          Buffer to copy client name to
+ * @param len           Maximum name buffer size
+ * @param authid        Buffer to copy client auth id to
+ * @param authidlen     Maximum authid buffer size
+ *
+ * @return              Next rank index (> 0 and > index), or 0 if no more
+ *                      statistics exist
+ */
 native get_stats(index, stats[8], bodyhits[8], name[], len, authid[] = "", authidlen = 0);
 
-/* Returns number of all entries in stats. */
+/**
+ * Returns the number of all entries in the permanent statistics storage.
+ *
+ * @return  Number of entries in statistics storage
+ */
 native get_statsnum();
 
-/*
+/**
-* new stats:
+ * Retrieves the client's objective statistics from the permanent storage.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note The fields in the statistics are:
  *          0 - total defusions
  *          1 - bomb defused
  *          2 - bomb plants
  *          3 - bomb explosions
+ *
+ * @param index     Client index
+ * @param stats     Buffer to copy statistics to
+ *
+ * @return          Players rank > 0 on success, or 0 if player is not ranked
+ *                  and no statistics are available
+ * @error           If an invalid client index is provided, an error will be
+ *                  thrown.
  */
 native get_user_stats2(index, stats[4]);
+
+/**
+ * Retrieves objective statistics from the permanent storage on the server via
+ * iterative, incremental access.
+ *
+ * @note The permanent storage is updated on every respawn or client disconnect.
+ * @note The fields in the statistics are:
+ *          0 - total defusions
+ *          1 - bomb defused
+ *          2 - bomb plants
+ *          3 - bomb explosions
+ *
+ * @param index         Client index
+ * @param stats         Buffer to copy statistics to
+ * @param authid        Buffer to copy client auth id to
+ * @param authidlen     Maximum authid buffer size
+ *
+ * @return              Next rank index (> 0 and > index), or 0 if no more
+ *                      statistics exist
+ */
 native get_stats2(index, stats[4], authid[] = "", authidlen = 0);

plugins/include/csx.inc

@@ -27,53 +27,9 @@
  #pragma library csx
 #endif
 
-/*
+/**
- * Forwards
+ * Map objective flags returned by get_map_objectives().
  */
-
-/* Function is called after player to player attacks ,
-* if players were damaged by teammate TA is set to 1 */
-forward client_damage(attacker,victim,damage,wpnindex,hitplace,TA);
-
-/* Function is called after player death ,
-* if player was killed by teammate TK is set to 1 */
-forward client_death(killer,victim,wpnindex,hitplace,TK);
-
-forward grenade_throw( index,greindex,wId );
-
-forward bomb_planting(planter);
-forward bomb_planted(planter);
-forward bomb_explode(planter,defuser);
-forward bomb_defusing(defuser);
-forward bomb_defused(defuser);
-
-/************* Shared Natives Start ********************************/
-
-/* Custom Weapon Support */
-/* function will return index of new weapon */
-native custom_weapon_add( const wpnname[],melee = 0,const logname[]="" ); 
-/* Function will pass damage done by this custom weapon to stats module and other plugins */
-native custom_weapon_dmg( weapon, att, vic, damage, hitplace=0 ); 
-/* Function will pass info about custom weapon shot to stats module */
-native custom_weapon_shot( weapon,index ); // weapon id , player id
-
-/* function will return 1 if true */
-native xmod_is_melee_wpn(wpnindex);
-
-/* Returns weapon name. */
-native xmod_get_wpnname(wpnindex,name[],len);
-
-/* Returns weapon logname. */
-native xmod_get_wpnlogname(wpnindex,name[],len);
-
-/* Returns weapons array size */
-native xmod_get_maxweapons();
-
-/* Returns stats array size */
-native xmod_get_stats_size();
-
-/************* Shared Natives End ********************************/
-
 enum MapObjective
 {
     MapObjective_Bomb    = (1<<0),
@@ -83,9 +39,225 @@ enum MapObjective
 };
 
 /**
- * Gets current map objectives.
+ * Called after a client attacks another client.
  *
- * @return 		Returns a bits sum if objectives are found, otherwise 0. 
+ * @note For a list of possible weapon ids see the CSW_* constants in
- * 				See MapObjective_* constants.
+ *       amxconst.inc
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param attacker  Attacker client index
+ * @param victim    Victim client index
+ * @param damage    Damage dealt to victim
+ * @param wpnindex  Weapon id
+ * @param hitplace  Body hitplace
+ * @param ta        If nonzero the attack was a team attack
+ *
+ * @noreturn
+ */
+forward client_damage(attacker, victim, damage, wpnindex, hitplace, TA);
+
+/**
+ * Called after a client death.
+ *
+ * @note For a list of possible weapon ids see the CSW_* constants in
+ *       amxconst.inc
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param attacker  Attacker client index
+ * @param victim    Victim client index
+ * @param wpnindex  Weapon id
+ * @param hitplace  Body hitplace
+ * @param tk        If nonzero the death was a teamkill
+ *
+ * @noreturn
+ */
+forward client_death(killer, victim, wpnindex, hitplace, TK);
+
+/**
+ * Called after a grenade was thrown.
+ *
+ * @note Weapon id is one of CSW_HEGRENADE, CSW_SMOKEGRENADE or CSW_FLASHBANG.
+ *
+ * @param index     Client index
+ * @param greindex  Grenade entity index
+ * @param wId       Weapon id
+ *
+ * @noreturn
+ */
+forward grenade_throw(index, greindex, wId);
+
+/**
+ * Called after a bomb plant attempt has started.
+ *
+ * @param planter   Planter client index
+ *
+ * @noreturn
+ */
+forward bomb_planting(planter);
+
+/**
+ * Called after a bomb plant has finished.
+ *
+ * @param planter   Planter client index
+ *
+ * @noreturn
+ */
+forward bomb_planted(planter);
+
+/**
+ * Called when the bomb exploded.
+ *
+ * @param planter   Planter client index
+ * @param defuser   Defuser client index, if applicable
+ *
+ * @noreturn
+ */
+forward bomb_explode(planter, defuser);
+
+/**
+ * Called after a bomb defuse attempt has started.
+ *
+ * @param defuser   Defuser client index
+ *
+ * @noreturn
+ */
+forward bomb_defusing(defuser);
+
+/**
+ * Called after a bomb defuse has finished.
+ *
+ * @param defuser   Defuser client index
+ *
+ * @noreturn
+ */
+forward bomb_defused(defuser);
+
+/**
+ * @section Shared natives
+ */
+
+/**
+ * Adds a custom weapon to the stats system.
+ *
+ * @note The weapon name should be the full display name of the gun such as
+ *       "Desert Eagle" while the logname should be "weapon_deagle".
+ *
+ * @param wpnname   Full weapon name
+ * @param melee     If nonzero the weapon will be considered a melee weapon
+ * @param logname   Weapon short name
+ *
+ * @return          Cusom weapon id (>0) on success, 0 if no more custom weapons
+ *                  can be added
+ */
+native custom_weapon_add(const wpnname[], melee = 0, const logname[] = "");
+
+/**
+ * Trigger a damage event on a custom weapon, adding it to the internal stats.
+ *
+ * @note This will also call the client_damage() and client_kill() forwards if
+ *       applicable.
+ * @note For a list of possible body hitplaces see the HIT_* constants in
+ *       amxconst.inc
+ *
+ * @param weapon    Custom weapon id
+ * @param att       Attacker client index
+ * @param vic       Victim client index
+ * @param damage    Damage dealt
+ * @param hitplace  Optional body hitplace
+ *
+ * @noreturn
+ * @error           If the weapon id is not a custom weapon, an invalid client
+ *                  index, damage value or hitplace is provided, an error will
+ *                  be thrown.
+ */
+native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0);
+
+/**
+ * Add a shot event on a custom weapon to the internal stats.
+ *
+ * @param weapon    Custom weapon id
+ * @param index     Client index
+ *
+ * @noreturn
+ * @error           If the weapon id is not a custom weapon or an invalid client
+ *                  index is provided, an error will be thrown.
+ */
+native custom_weapon_shot(weapon, index); // weapon id , player id
+
+/**
+ * Returns if the weapon is considered a melee weapon.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ *
+ * @return          1 if weapon is a melee weapon, 0
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_is_melee_wpn(wpnindex);
+
+/**
+ * Retrieves the full weapon name of a weapon id.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ * @param name      Buffer to copy weapon name to
+ * @param len       Maximmum buffer size
+ *
+ * @return          Number of cells written to buffer
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_get_wpnname(wpnindex, name[], len);
+
+/**
+ * Retrieves the weapon log name of a weapon id.
+ *
+ * @note For a list of default CS weapon ids see the CSW_* constants in
+ *       amxconst.inc, this function also works on custom weapons.
+ * @note For the default CS weapons this obviously returns true only for
+ *       CSW_KNIFE.
+ *
+ * @param wpnindex  Weapon id
+ * @param name      Buffer to copy weapon log name to
+ * @param len       Maximmum buffer size
+ *
+ * @return          Number of cells written to buffer
+ * @error           If an invalid weapon id is provided an error will be thrown.
+ */
+native xmod_get_wpnlogname(wpnindex, name[], len);
+
+/**
+ * Returns the maximum amount of weapons that the stats system supports.
+ *
+ * @return      Maximum number of weapons supported
+ */
+native xmod_get_maxweapons();
+
+/**
+ * Returns the number of stats tracked by the stats system.
+ *
+ * @return      Number of stats tracked
+ */
+native xmod_get_stats_size();
+
+/**
+ * @endsection Shared natives
+ */
+
+/**
+ * Returns the current map's objectives as a bitflag value.
+ *
+ * @note For a list of possible map objective flags see the MapObjective enum.
+ *
+ * @return      Bitflag value of map objectives
  */
 native MapObjective:get_map_objectives();