Merge pull request #239 from Nextra/inc-doc3

Update include documentation #3 (mostly engine.inc)

plugins/include/cstrike.inc

@@ -642,8 +642,8 @@ native cs_set_user_armor(index, armorvalue, CsArmorType:armortype);
  *
  * @note Only the Glock and Famas can return 1 as they are the only guns in the
  *       game that have a burst fire mode.
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will return incorrect values for non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will return incorrect values for non-weapon entities.
  *
  * @param index     Weapon entity index
  *
@@ -658,9 +658,9 @@ native cs_get_weapon_burst(index);
  *
  * @note Only the Glock and Famas can be set to burst fire mode as they are the
  *       only guns in the game that provide such a mode.
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will result in undefined behavior if used on
- *       non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will result in undefined behavior if used on non-weapon
+ *       entities.
  *
  * @param index         Weapon entity index
  * @param burstmode     If nonzero the weapon will be put into burstmode,
@@ -678,8 +678,8 @@ native cs_set_weapon_burst(index, burstmode = 1);
  *
  * @note Only the USP and M4A1 can return 1 as they are the only guns in the
  *       game that have a silenced fire mode.
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will return incorrect values for non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will return incorrect values for non-weapon entities.
  *
  * @param index     Weapon entity index
  *
@@ -694,9 +694,9 @@ native cs_get_weapon_silen(index);
  *
  * @note Only the USP and M4A1 can be set to silenced fire mode as they are the
  *       only guns in the game that provide such a mode.
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will result in undefined behavior if used on
- *       non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will result in undefined behavior if used on non-weapon
+ *       entities.
  *
  * @param index             Weapon entity index
  * @param silence           If nonzero the weapon will be put into silenced
@@ -715,8 +715,8 @@ native cs_set_weapon_silen(index, silence = 1, draw_animation = 1);
 /**
  * Returns the amount of ammo in weapon's magazine.
  *
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will return incorrect values for non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will return incorrect values for non-weapon entities.
  *
  * @param index     Weapon entity index
  *
@@ -729,9 +729,9 @@ native cs_get_weapon_ammo(index);
 /**
  * Sets the amount of ammo in weapon's clip.
  *
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will result in undefined behavior if used on
- *       non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will result in undefined behavior if used on non-weapon
+ *       entities.
  *
  * @param index     Weapon entity index
  * @param newammo   New ammo amount
@@ -747,8 +747,8 @@ native cs_set_weapon_ammo(index, newammo);
  *
  * @note For a list of possible weapon ids see the CSW_* constants in
  *       amxconst.inc
- * @note This native does not check that the provided entity is actually a
- *       weapon entity. It will return incorrect values for non-weapon entities.
+ * @note This native does not verify that the provided entity is a weapon
+ *       entity. It will return incorrect values for non-weapon entities.
  *
  * @param index     Weapon entity index
  *
@@ -973,8 +973,8 @@ native cs_get_user_hostagekills(index);
  * @note This is the value that the internal Counter-Strike hostage punisher
  *       uses to determine if a client should be kicked, depending on the
  *       value of the mp_hostagepenalty value. The punisher only checks this
- *       value when a hostage is actually killed, so setting this will not cause
- *       a client to be kicked until they actually kill a hostage.
+ *       value when a hostage is killed, so setting this will not cause the
+ *       client to be kicked until they actually kill a hostage.
  *
  * @param index     Client index
  * @param value     New amount of hostages killed
@@ -1093,6 +1093,11 @@ native cs_set_c4_defusing(c4index, bool:defusing);
  *         automatically cleaned up on round restart but are not considered if
  *         they have not been added to the hashtable.
  * @note The faster hashtable lookup can be utilized with cs_find_ent_by_class()
+ * @note When creating an entity the classname has to be valid in the mod, as
+ *       the engine needs to link the entity to an existing class internally.
+ *       The classname string that is stored in the entvar struct
+ *       (EV_SZ_classname) is separate from this association and can later be
+ *       freely changed to serve other purposes.
  *
  * @param classname     Entity class name
  *
@@ -1137,8 +1142,7 @@ forward CS_InternalCommand(id, const cmd[]);
  * Called when a client attempts to purchase an item.
  *
  * @note This is called immediately when the client issues a buy command. The
- *       game has not actually checked if the client can actually buy the
- *       weapon.
+ *       game has not yet checked if the client can actually buy the weapon.
  * @note For a list of possible item ids see the CSI_* constants.
  *
  * @param index     Client index

plugins/include/datapack.inc

@@ -147,10 +147,9 @@ native SetPackPosition(DataPack:pack, position);
  * @param pack      Datapack handle
  *
  * @return          True if datapack has reached the end, false otherwise
- * @error           If an invalid handle is provided, or the new position is
- *                  out of datapack bounds, an error will be thrown.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
- native bool:IsPackEnded(DataPack:pack);
+native bool:IsPackEnded(DataPack:pack);
 
 /**
  * Destroys the datapack and frees its memory.

plugins/include/engine_const.inc

@@ -18,17 +18,35 @@
 
 #include <hlsdk_const>
 
-#define SPEAK_NORMAL	0
-#define SPEAK_MUTED		1
-#define SPEAK_ALL		2
-#define SPEAK_LISTENALL	4
+/**
+ * Flags for the [set|get]_speak() natives.
+ *
+ * @note These do not correspond to any HLSDK constants and are only relevant to
+ *       the custom functionality provided by the engine module.
+ */
+#define SPEAK_NORMAL        0 // Normal behavior, client follows alltalk rules
+#define SPEAK_MUTED         1 // Client can not talk
+#define SPEAK_ALL           2 // Client can talk to every other client
+#define SPEAK_LISTENALL     4 // Client can listen to every other client
 
+/**
+ * View types for the set_view() native.
+ *
+ * @note These do not correspond to any HLSDK constants and are only relevant to
+ * 		 the custom functionality provided by the engine module.
+ */
 #define CAMERA_NONE         0
 #define CAMERA_3RDPERSON    1
 #define CAMERA_UPLEFT       2
 #define CAMERA_TOPDOWN      3
 
-/* Int */
+/**
+ * @section Entvar constants used with entity_[get|set]_* functions.
+ */
+
+/**
+ * Integers, use with entity_[get|set]_int()
+ */
 enum {
 	EV_INT_gamestate = 0,
 	EV_INT_oldbuttons,
@@ -69,7 +87,9 @@ enum {
 	EV_INT_deadflag,
 };
 
-/* Float */
+/**
+ * Floats, use with entity_[get|set]_float()
+ */
 enum {
 	EV_FL_impacttime = 0,
 	EV_FL_starttime,
@@ -110,7 +130,9 @@ enum {
 	EV_FL_fuser4,
 };
 
-/* Vector */
+/**
+ * Vectors, use with entity_[get|set]_vector()
+ */
 enum {
 	EV_VEC_origin = 0,
 	EV_VEC_oldorigin,
@@ -137,7 +159,9 @@ enum {
 	EV_VEC_vuser4,
 };
 
-/* Edict */
+/**
+ * Edicts, use with entity_[get|set]_edict()
+ */
 enum {
 	EV_ENT_chain = 0,
 	EV_ENT_dmg_inflictor,
@@ -152,7 +176,9 @@ enum {
 	EV_ENT_euser4,
 };
 
-/* String */
+/**
+ * Strings, use with entity_[get|set]_string()
+ */
 enum {
 	EV_SZ_classname = 0,
 	EV_SZ_globalname,
@@ -169,7 +195,9 @@ enum {
 	EV_SZ_weaponmodel,
 };
 
-/* Byte */
+/**
+ * Bytearrays, use with entity_[get|set]_byte()
+ */
 enum {
 	EV_BYTE_controller1 = 0,
 	EV_BYTE_controller2,
@@ -179,6 +207,10 @@ enum {
 	EV_BYTE_blending2,
 };
 
+/**
+ * @endsection
+ */
+
 #if defined _jghg_enums
   #endinput
 #endif

plugins/include/hlsdk_const.inc

@@ -77,6 +77,12 @@
 #define WALKMOVE_WORLDONLY              1           // Doesn't hit ANY entities, no matter what the solid type
 #define WALKMOVE_CHECKONLY              2           // Move, but don't touch triggers
 
+/**
+ * engfunc(EngFunc_MoveToOrigin, entity, Float:goal[3], Float:distance, moveType) moveType values
+ */
+#define MOVE_NORMAL                     0           // normal move in the direction monster is facing
+#define MOVE_STRAFE                     1           // moves in direction specified, no matter which way monster is facing
+
 /**
  * pev(entity, pev_movetype) values
  */
@@ -234,6 +240,7 @@
 /**
  * @section pev(entity, pev_spawnflags) values
  */
+
 /**
  * func_train
  */