Merge pull request #49 from NexiusTailer/master

Corrections in docs, add natives

Author: AmyrAhmady

documentation/readme-expert.md

@@ -167,16 +167,14 @@ You will note that all these new features either use existing keywords, `#`, or
 
 ### More Tags
 
-open.mp includes introduce many more tags to functions and callbacks.  These are useful in the long run, but slightly annoying to upgrade to.  There are three symbols:  `NO_TAGS`, `WEAK_TAGS`, and `STRONG_TAGS`; that you can define before including `<open.mp>`, each one enabling progressively more checks.
-
-To make the transition easier, the default is `NO_TAGS`, but you can also make tags *weak*:
+open.mp includes introduce many more tags to functions and callbacks.  These are useful in the long run, but slightly annoying to upgrade to.  There are three symbols:  `NO_TAGS`, `WEAK_TAGS`, and `STRONG_TAGS`; that you can define before including `<open.mp>`, each one enabling progressively more checks:
 
 ```pawn
-#define WEAK_TAGS
+#define STRONG_TAGS
 #include <open.mp>
 ```
 
-In this case, most old code uses will simply give a warning when the wrong tag is found:
+To encourage some adoption, the default is `WEAK_TAGS`.  Most old code uses will simply give a warning when the wrong tag is found:
 
 ```pawn
 // Gives a warning:
@@ -218,17 +216,17 @@ You can enable `void:` tag warnings with a define before including `open.mp`, th
 #include <open.mp>
 ```
 
-Again, you can make these new tags *weak*, meaning that you get warnings when passing untagged values to tagged parameters, but not the other way around.  This applies to function returns so saving a tag result in an untagged variable will not give a warning:
+For parameters the default is to make these new tags *weak*, meaning that you get warnings when passing untagged values to tagged parameters, but not the other way around.  This applies to function returns so saving a tag result in an untagged variable will not give a warning.  This second group can also be upgraded by specifying the use of *strong* tags instead:
 
 ```pawn
-#define WEAK_TAGS
+#define STRONG_TAGS
 #include <open.mp>
 ```
 
-This second group can also be upgraded by specifying the use of *strong* tags instead:
+Alternatively, if you need to move your legacy codebase as is:
 
 ```pawn
-#define STRONG_TAGS
+#define NO_TAGS
 #include <open.mp>
 ```
 
@@ -362,7 +360,11 @@ native GetServerVarAsString(const cvar[], buffer[], len = sizeof (buffer));
 
 ### Spelling Consistency
 
-The SA:MP includes had a mixture of both English (`Bumper`, `Armour`, `Petrol`, etc) and American (`Color`, `Hood`, `Stereo`, etc) spellings of words.  The open.mp includes have introduced *more* variants, for example `Trunk` has now been added as an alternative spelling to `Boot`; but along-side this change have settled on canonical and deprecated variants.  In line with the code in the server itself, the English spellings are the preferred variants going forwards.
+The SA:MP includes had a mixture of both British English (`Bumper`, `Armour`, `Petrol`, etc) and American English (`Color`, `Hood`, `Stereo`, etc) spellings of words.  The open.mp includes have introduced *more* variants, for example `Trunk` has now been added as an alternative spelling to `Boot`; but along-side this change have settled on canonical and deprecated variants.  In line with the code in the server itself, the British spellings are the preferred variants going forwards; and while American spellings will continue to be supported indefinitely some have had warnings added to notify users of this consistency improvement.  if you wish to stick with the mixed spellings you can add a define to the top of your code:
+
+```pawn
+#define MIXED_SPELLINGS
+```
 
  Function Changes
 ------------------

documentation/readme-intermediate.md

@@ -126,17 +126,17 @@ main()
 }
 ```
 
-To make the transition easier, the default is `NO_TAGS`.  The tags can also be *weak* - passing an integer instead of an enum value is a warning, but the reverse isn't:
+The tags are all *weak* - passing an integer instead of an enum value is a warning, but the reverse isn't.  The latter can be enabled by making the tags *strong*:
 
 ```pawn
-#define WEAK_TAGS
+#define STRONG_TAGS
 #include <open.mp>
 ```
 
-The latter can be enabled by making the tags *strong*:
+Alternatively, if you need to move your legacy codebase as is:
 
 ```pawn
-#define STRONG_TAGS
+#define NO_TAGS
 #include <open.mp>
 ```
 

omp_actor.inc

@@ -372,6 +372,12 @@ native bool:GetActorSpawnInfo(actorid, &skin, &Float:spawnX = 0.0, &Float:spawnY
 
 /**
  * <library>omp_actor</library>
+ * <summary>Get an array variable of the IDs of the created actors on the server.</summary>
+ * <param name="actors">An array into which to store the actor IDs, passed by reference.</param>
+ * <param name="size">The size of the array.</param>
+ * <seealso name="GetPlayers" />
+ * <seealso name="GetVehicles" />
+ * <returns>The number of actors stored in the array.</returns>
  */
 native GetActors(actors[], size = sizeof (actors));
 

omp_network.inc

@@ -501,6 +501,20 @@ native Float:NetStats_PacketLossPercent(playerid);
  */
 native CONNECTION_STATUS:NetStats_ConnectionStatus(playerid);
 
+/**
+ * <library>omp_network</library>
+ * <summary>Gets the player's current connection status.</summary>
+ * <param name="playerid">The ID of the player to get the connection status of</param>
+ * <seealso name="NetStats_ConnectionStatus" />
+ * <seealso name="GetPlayerNetworkStats" />
+ * <seealso name="GetNetworkStats" />
+ * <seealso name="IsPlayerConnected" />
+ * <seealso name="OnPlayerConnect" />
+ * <seealso name="OnPlayerDisconnect" />
+ * <returns>The player's connection status, as an integer value.</returns>
+ */
+native CONNECTION_STATUS:GetPlayerConnectMode(playerid) = NetStats_ConnectionStatus;
+
 /**
  * <library>omp_network</library>
  * <summary>Get a player's IP and port.</summary>

omp_object.inc

@@ -1142,7 +1142,7 @@ native Float:GetPlayerObjectMoveSpeed(playerid, objectid);
  * <library>omp_object</library>
  * <summary></summary>
  */
-native Float:GetPlayerObjectTarget(playerid, objectid, &Float:targetX = 0.0, &Float:targetY = 0.0, &Float:targetZ = 0.0);
+native bool:GetPlayerObjectTarget(playerid, objectid, &Float:targetX = 0.0, &Float:targetY = 0.0, &Float:targetZ = 0.0) = GetPlayerObjectMovingTargetPos;
 
 /**
  * <library>omp_object</library>

omp_player.inc

@@ -1590,7 +1590,7 @@ native bool:SendClientMessage(playerid, colour, const format[], OPEN_MP_TAGS:...
  *   <b><c>0</c></b>: The function failed to execute.  The player is not connected.
  * </returns>
  */
-#pragma deprecated Use `SendClientMessagef`
+#pragma deprecated Use `SendClientMessage`
 native bool:SendClientMessagef(playerid, colour, const format[], OPEN_MP_TAGS:...) = SendClientMessage;
 
 /**
@@ -1627,7 +1627,7 @@ native bool:GameTextForPlayer(playerid, const format[], time, style, OPEN_MP_TAG
  * is not connected.
  * </returns>
  */
-#pragma deprecated Use `GameTextForPlayerf`
+#pragma deprecated Use `GameTextForPlayer`
 native bool:GameTextForPlayerf(playerid, const format[], time, style, OPEN_MP_TAGS:...) = GameTextForPlayer;
 
 /**
@@ -2860,41 +2860,143 @@ native Float:GetPlayerCameraZoom(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Check if the player camera target is enabled.</summary>
+ * <param name="playerid">The ID of the player to check the camera target is enabled.</param>
+ * <seealso name="EnablePlayerCameraTarget" />
+ * <returns>
+ *   <b><c>1</c></b>: If camera target enabled.<br />
+ *   <b><c>0</c></b>: If camera target not enabled or the player specified does not exist.
+ * </returns>
  */
 native bool:IsPlayerCameraTargetEnabled(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Toggle player's widescreen.</summary>
+ * <param name="playerid">The ID of the player to toggle the widescreen.</param>
+ * <param name="wide">true for turn on and false for turn off.</param>
+ * <seealso name="IsPlayerWidescreenToggled" />
+ * <returns>
+ *   <b><c>1</c></b>: The function was executed successfully.<br />
+ *   <b><c>0</c></b>: The function failed to execute. This means the player specified does not exist.
+ * </returns>
  */
 native bool:TogglePlayerWidescreen(playerid, bool:wide);
 
 /**
  * <library>omp_player</library>
+ * <summary>Checks if a player widescreen is on or off.</summary>
+ * <param name="playerid">The ID of the player to check.</param>
+ * <seealso name="TogglePlayerWidescreen" />
+ * <returns>
+ *   <b><c>1</c></b>: The player widescreen is on.<br />
+ *   <b><c>0</c></b>: The player widescreen is off or the player specified does not exist.
+ * </returns>
  */
 native bool:IsPlayerWidescreenToggled(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Get the ID of the player or vehicle the player is spectating.</summary>
+ * <param name="playerid">The ID of the player.</param>
+ * <seealso name="PlayerSpectatePlayer" />
+ * <seealso name="PlayerSpectateVehicle" />
+ * <seealso name="TogglePlayerSpectating" />
+ * <seealso name="GetPlayerSpectateType" />
+ * <returns>ID of the player or vehicle.</returns>
  */
 native GetPlayerSpectateID(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Returns the player's spectate type.</summary>
+ * <param name="playerid">The ID of the player to get spectate type of.</param>
+ * <seealso name="PlayerSpectatePlayer" />
+ * <seealso name="PlayerSpectateVehicle" />
+ * <seealso name="TogglePlayerSpectating" />
+ * <seealso name="GetPlayerSpectateID" />
+ * <returns>The player's spectate type.</returns>
  */
 native GetPlayerSpectateType(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Get the player animation flags.</summary>
+ * <param name="playerid">The player id you want to get the animation flags from.</param>
+ * <seealso name="ApplyAnimation" />
+ * <returns>The player animation flags as an integer.</returns>
+ */
+native GetPlayerAnimFlags(playerid);
+
+/**
+ * <library>omp_player</library>
+ * <summary>Get the player animation flags.</summary>
+ * <param name="playerid">The player id you want to get the animation flags from.</param>
+ * <seealso name="ApplyAnimation" />
+ * <returns>The player animation flags as an integer.</returns>
+ */
+native GetPlayerAnimationFlags(playerid) = GetPlayerAnimFlags;
+
+/**
+ * <library>omp_player</library>
+ * <summary>Check if the player is in driveby mode.</summary>
+ * <param name="playerid">The ID of the player to check.</param>
+ * <returns>
+ *   <b><c>1</c></b>: The player is in driveby mode.<br />
+ *   <b><c>0</c></b>: The player is not in driveby mode or the player specified does not exist.
+ * </returns>
+ */
+native bool:IsPlayerInDriveByMode(playerid);
+
+/**
+ * <library>omp_player</library>
+ * <summary>Check if the player special action is cuffed.</summary>
+ * <param name="playerid">The ID of the player to check.</param>
+ * <returns>
+ *   <b><c>1</c></b>: The player is cuffed.<br />
+ *   <b><c>0</c></b>: The player is not cuffed or the player specified does not exist.
+ * </returns>
+ */
+native bool:IsPlayerCuffed(playerid);
+
+/**
+ * <library>omp_player</library>
+ * <summary>Gets a player's Z Aim (related to the camera and aiming).</summary>
+ * <param name="playerid">The ID of the player to get Z Aim of.</param>
+ * <seealso name="GetPlayerCameraPos" />
+ * <returns>The player's Z Aim as a float value.</returns>
  */
 native Float:GetPlayerZAim(playerid);
 
 /**
  * <library>omp_player</library>
+ * <summary>Gets a player's Z Aim (related to the camera and aiming).</summary>
+ * <param name="playerid">The ID of the player to get Z Aim of.</param>
+ * <seealso name="GetPlayerCameraPos" />
+ * <returns>The player's Z Aim as a float value.</returns>
+ */
+native Float:GetPlayerAimZ(playerid) = GetPlayerZAim;
+
+/**
+ * <library>omp_player</library>
+ * <summary>Get an array variable of the IDs of the current players on the server.</summary>
+ * <param name="players">An array into which to store the player IDs, passed by reference.</param>
+ * <param name="size">The size of the array.</param>
+ * <seealso name="GetVehicles" />
+ * <seealso name="GetActors" />
+ * <returns>The number of players stored in the array.</returns>
  */
 native GetPlayers(players[], size = sizeof (players));
 
 /**
  * <library>omp_player</library>
+ * <summary>Check if the player is using the official SA-MP client.</summary>
+ * <param name="playerid">The ID of the player to check.</param>
+ * <seealso name="SendClientCheck" />
+ * <returns>
+ *   <b><c>1</c></b>: The player is using official client.<br />
+ *   <b><c>0</c></b>: The player is not using official client or the player specified does not exist.
+ * </returns>
  */
 native bool:IsPlayerUsingOfficialClient(playerid);
 

omp_textdraw.inc

@@ -386,7 +386,7 @@ native bool:TextDrawSetOutline(Text:textid, outlineSize);
  * after modifying the textdraw and the change will be visible.</remarks>
  */
 #if !defined MIXED_SPELLINGS
-	#pragma deprecated Use `TextDrawBackgroundColor`. To silence this warning and use different spellings define `MIXED_SPELLINGS` or define `SAMP_COMPAT` for general SA-MP API compatibility.
+	#pragma deprecated Use `TextDrawBackgroundColour`. To silence this warning and use different spellings define `MIXED_SPELLINGS` or define `SAMP_COMPAT` for general SA-MP API compatibility.
 #endif
 native bool:TextDrawBackgroundColor(Text:textid, backgroundColor);
 

omp_vehicle.inc

@@ -877,9 +877,9 @@ native bool:AddVehicleComponent(vehicleid, component);
 /**
  * <library>omp_vehicle</library>
  * <summary>Remove a component from a vehicle.</summary>
- * <param name="vehicleid">ID of the vehicle</param>
+ * <param name="vehicleid">ID of the vehicle.</param>
  * <param name="component">ID of the <a href="https://www.open.mp/docs/scripting/resources/carcomponentid">component</a>
- * to remove</param>
+ * to remove.</param>
  * <seealso name="AddVehicleComponent" />
  * <seealso name="GetVehicleComponentInSlot" />
  * <seealso name="GetVehicleComponentType" />
@@ -891,9 +891,9 @@ native bool:RemoveVehicleComponent(vehicleid, component);
 /**
  * <library>omp_vehicle</library>
  * <summary>Is this component legal on this vehicle?</summary>
- * <param name="vehicleid">ID of the vehicle</param>
+ * <param name="vehicleid">ID of the vehicle.</param>
  * <param name="component">ID of the <a href="https://www.open.mp/docs/scripting/resources/carcomponentid">component</a>
- * to remove</param>
+ * to check.</param>
  * <seealso name="AddVehicleComponent" />
  * <seealso name="GetVehicleComponentInSlot" />
  * <seealso name="GetVehicleComponentType" />
@@ -904,11 +904,24 @@ native bool:VehicleCanHaveComponent(vehicleid, componentid);
 
 /**
  * <library>omp_vehicle</library>
- * <summary>Get the number of seats in this vehicle</summary>
- * <param name="vehicleid">ID of the vehicle</param>
+ * <summary>Gets the number of seats for a vehicle model.</summary>
+ * <param name="vehicleid">ID of the vehicle model.</param>
+ * <returns>
+ *   <b><c>number of seats</c></b>: The number of seats as an integer.<br />
+ * </returns>
  */
 native GetVehicleSeats(vehicleid);
 
+/**
+ * <library>omp_vehicle</library>
+ * <summary>Gets the number of seats for a vehicle model.</summary>
+ * <param name="modelid">The ID of the vehicle model.</param>
+ * <returns>
+ *   <b><c>number of seats</c></b>: The number of seats as an integer.<br />
+ * </returns>
+ */
+native GetVehicleMaxPassengers(vehicleid) = GetVehicleSeats;
+
 /**
  * <library>omp_vehicle</library>
  * <summary>Change a vehicle's primary and secondary colours.</summary>
@@ -1616,6 +1629,12 @@ native void:EnableVehicleFriendlyFire();
 
 /**
  * <library>omp_vehicle</library>
+ * <summary>Get an array variable of the IDs of the created vehicles on the server.</summary>
+ * <param name="vehicles">An array into which to store the vehicle IDs, passed by reference.</param>
+ * <param name="size">The size of the array.</param>
+ * <seealso name="GetPlayers" />
+ * <seealso name="GetActors" />
+ * <returns>The number of vehicles stored in the array.</returns>
  */
 native GetVehicles(vehicles[], size = sizeof (vehicles));
 
@@ -1632,16 +1651,6 @@ native GetVehicles(vehicles[], size = sizeof (vehicles));
  */
 native GetVehicleOccupant(vehicleid, seatid);
 
-/**
- * <library>omp_vehicle</library>
- * <summary>Gets the number of seats for a vehicle model.</summary>
- * <param name="modelid">The ID of the model.</param>
- * <returns>
- *   <b><c>number of seats</c></b>: The number of seats as an intiger.<br />
- * </returns>
- */
-native GetVehicleMaxPassengers(modelid);
-
 /**
  * <library>omp_vehicle</library>
  * <summary>Returns the number of occupants in the given vehicle.</summary>