docs: [1.X] fixes of PVP exceptions (#3300)

This PR focuses on fixing PVP errors related to PVP-151-1 "**_Public
APIs should be documented_**" and all remaining PVP errors **present in
pvpExceptions.json file**

We have quite a lot of errors to address so this PR will be a
collaborative effort. If anyone want's to add to it what we should do
is:

1. Check errors present in pvpExceptions.json file (preferably under
"PVP-150-1", choose some to fix
2. Address those errors and when making commit remove the fixed errors
from pvpExceptions file
The first commit of this PR is an example of how such process should
look like

In general [new CI
implementation](#3193)
will catch all new errors like this so all we need to do is fix the
present ones. This PR **does not** focus on PVP present in gold profile
but if capacity allows, those can also be addressed.

**Error present in "PVP-41-1" is to be expected** so there is no need of
fixing this one!

Another thing is that we could ignore error related to missing APIs for
RuntimeTests because those were made internal in 2.X version (that's why
those errors are not popping by there). Those APIs are not user facing
so we could just leave them (otherwise there is like 2000 more APIs to
add)

---------

Co-authored-by: Noel Stephens <[email protected]>
Co-authored-by: Emma <[email protected]>
Co-authored-by: unity-renovate[bot] <120015202+unity-renovate[bot]@users.noreply.github.com>

Author: 4 people

.yamato/wrench/package-pack-jobs.yml

@@ -26,3 +26,4 @@ package_pack_-_netcode_gameobjects:
     Job Maintainers: '#rm-packageworks'
     Wrench: 0.10.44.0
 
+

com.unity.netcode.gameobjects/Components/AnticipatedNetworkTransform.cs

@@ -46,10 +46,24 @@ namespace Unity.Netcode.Components
     [DefaultExecutionOrder(100000)] // this is needed to catch the update time after the transform was updated by user scripts
     public class AnticipatedNetworkTransform : NetworkTransform
     {
+        /// <summary>
+        /// Represents the state of a transform, including position, rotation, and scale.
+        /// </summary>
         public struct TransformState
         {
+            /// <summary>
+            /// The position of the transform.
+            /// </summary>
             public Vector3 Position;
+
+            /// <summary>
+            /// The rotation of the transform.
+            /// </summary>
             public Quaternion Rotation;
+
+            /// <summary>
+            /// The scale of the transform.
+            /// </summary>
             public Vector3 Scale;
         }
 
@@ -242,6 +256,9 @@ public void AnticipateState(TransformState newState)
             m_CurrentSmoothTime = 0;
         }
 
+        /// <summary>
+        /// Updates the AnticipatedNetworkTransform each frame.
+        /// </summary>
         protected override void Update()
         {
             // If not spawned or this instance has authority, exit early
@@ -350,6 +367,13 @@ private void ResetAnticipatedState()
             m_CurrentSmoothTime = 0;
         }
 
+        /// <summary>
+        /// Invoked when a new client joins (server and client sides).
+        /// Server Side: Serializes as if we were teleporting (everything is sent via NetworkTransformState).
+        /// Client Side: Adds the interpolated state which applies the NetworkTransformState as well.
+        /// </summary>
+        /// <typeparam name="T">The type of the serializer.</typeparam>
+        /// <param name="serializer">The serializer used to serialize the state.</param>
         protected override void OnSynchronize<T>(ref BufferSerializer<T> serializer)
         {
             base.OnSynchronize(ref serializer);
@@ -361,6 +385,9 @@ protected override void OnSynchronize<T>(ref BufferSerializer<T> serializer)
             }
         }
 
+        /// <summary>
+        /// Invoked when the NetworkObject is spawned.
+        /// </summary>
         public override void OnNetworkSpawn()
         {
             base.OnNetworkSpawn();
@@ -373,6 +400,9 @@ public override void OnNetworkSpawn()
             NetworkManager.AnticipationSystem.AllAnticipatedObjects.Add(m_AnticipatedObject);
         }
 
+        /// <summary>
+        /// Invoked when the NetworkObject is despawned.
+        /// </summary>
         public override void OnNetworkDespawn()
         {
             if (m_AnticipatedObject != null)
@@ -387,6 +417,9 @@ public override void OnNetworkDespawn()
             base.OnNetworkDespawn();
         }
 
+        /// <summary>
+        /// Invoked when the NetworkObject is destroyed.
+        /// </summary>
         public override void OnDestroy()
         {
             if (m_AnticipatedObject != null)
@@ -438,19 +471,30 @@ public void Smooth(TransformState from, TransformState to, float durationSeconds
             m_CurrentSmoothTime = 0;
         }
 
+        /// <summary>
+        /// Invoked just before the authoritative state is updated and pushed to non-authoritative instances.
+        /// </summary>
         protected override void OnBeforeUpdateTransformState()
         {
             // this is called when new data comes from the server
             m_LastAuthorityUpdateCounter = NetworkManager.AnticipationSystem.LastAnticipationAck;
             m_OutstandingAuthorityChange = true;
         }
 
+        /// <summary>
+        /// Invoked when the NetworkTransform state is updated.
+        /// </summary>
+        /// <param name="oldState">The previous state of the NetworkTransform.</param>
+        /// <param name="newState">The new state of the NetworkTransform.</param>
         protected override void OnNetworkTransformStateUpdated(ref NetworkTransformState oldState, ref NetworkTransformState newState)
         {
             base.OnNetworkTransformStateUpdated(ref oldState, ref newState);
             ApplyAuthoritativeState();
         }
 
+        /// <summary>
+        /// Invoked whenever the transform has been updated.
+        /// </summary>
         protected override void OnTransformUpdated()
         {
             if (CanCommitToTransform || m_AnticipatedObject == null)

com.unity.netcode.gameobjects/Components/HalfVector3.cs

@@ -77,6 +77,8 @@ private void SerializeRead(FastBufferReader reader)
         /// <summary>
         /// The serialization implementation of <see cref="INetworkSerializable"/>.
         /// </summary>
+        /// <typeparam name="T">The type of the serializer.</typeparam>
+        /// <param name="serializer">The serializer used to serialize or deserialize the state.</param>
         public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
         {
             if (serializer.IsReader)

com.unity.netcode.gameobjects/Components/HalfVector4.cs

@@ -61,6 +61,8 @@ private void SerializeRead(FastBufferReader reader)
         /// <summary>
         /// The serialization implementation of <see cref="INetworkSerializable"/>.
         /// </summary>
+        /// <typeparam name="T">The type of the serializer.</typeparam>
+        /// <param name="serializer">The serializer used to serialize or deserialize the state.</param>
         public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
         {
             if (serializer.IsReader)

com.unity.netcode.gameobjects/Components/NetworkDeltaPosition.cs

@@ -30,6 +30,8 @@ public struct NetworkDeltaPosition : INetworkSerializable
         /// <summary>
         /// The serialization implementation of <see cref="INetworkSerializable"/>
         /// </summary>
+        /// <typeparam name="T">The type of the serializer.</typeparam>
+        /// <param name="serializer">The serializer used to serialize or deserialize the state.</param>
         public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
         {
             if (!SynchronizeBase)
@@ -105,6 +107,7 @@ public Vector3 GetFullPosition()
         /// <remarks>
         /// Only applies to the authoritative side for <see cref="NetworkTransform"/> instances.
         /// </remarks>
+        /// <returns>The current delta position as a <see cref="Vector3"/> with half float precision.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Vector3 GetConvertedDelta()
         {
@@ -120,6 +123,7 @@ public Vector3 GetConvertedDelta()
         /// Precision loss adjustments are one network tick behind on the
         /// non-authoritative side.
         /// </remarks>
+        /// <returns>The current delta position as a <see cref="Vector3"/>.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Vector3 GetDeltaPosition()
         {

com.unity.netcode.gameobjects/Components/NetworkTransform.cs

@@ -66,7 +66,7 @@ public class NetworkTransform : NetworkBehaviour
         /// - The teleporting state update.
         /// - When using half float precision and the `NetworkDeltaPosition` delta exceeds the maximum delta forcing the axis in
         /// question to be collapsed into the core base position, this state update will be sent as reliable fragmented sequenced.
-        /// 
+        ///
         /// In order to preserve a continual consistency of axial values when unreliable delta messaging is enabled (due to the
         /// possibility of dropping packets), NetworkTransform instances will send 1 axial frame synchronization update per
         /// second (only for the axis marked to synchronize are sent as reliable fragmented sequenced) as long as a delta state
@@ -104,7 +104,7 @@ public struct NetworkTransformState : INetworkSerializable
             private const int k_ReliableSequenced = 0x00080000;
             private const int k_UseUnreliableDeltas = 0x00100000;
             private const int k_UnreliableFrameSync = 0x00200000;
-            private const int k_TrackStateId = 0x10000000; // (Internal Debugging) When set each state update will contain a state identifier 
+            private const int k_TrackStateId = 0x10000000; // (Internal Debugging) When set each state update will contain a state identifier
 
             // Stores persistent and state relative flags
             private uint m_Bitset;
@@ -459,10 +459,11 @@ internal set
             }
 
             /// <summary>
-            /// Returns whether this state update was a frame synchronization when 
-            /// UseUnreliableDeltas is enabled. When set, the entire transform will 
+            /// Returns whether this state update was a frame synchronization when
+            /// UseUnreliableDeltas is enabled. When set, the entire transform will
             /// be or has been synchronized.
             /// </summary>
+            /// <returns><see cref="true"/> if this state update was a frame synchronization; otherwise, <see cref="false"/>.</returns>
             public bool IsUnreliableFrameSync()
             {
                 return UnreliableFrameSync;
@@ -475,6 +476,7 @@ public bool IsUnreliableFrameSync()
             /// <remarks>
             /// Unreliable delivery will only be used if <see cref="UseUnreliableDeltas"/> is set.
             /// </remarks>
+            /// <returns><see cref="true"/> if this state was sent with reliable delivery; otherwise, <see cref="false"/>.</returns>
             public bool IsReliableStateUpdate()
             {
                 return ReliableSequenced;
@@ -586,7 +588,7 @@ public Quaternion GetRotation()
             /// <remarks>
             /// When there is no change in an updated state's position then there are no values to return.
             /// Checking for <see cref="HasPositionChange"/> is one way to detect this.
-            /// When used with half precision it returns the half precision delta position state update 
+            /// When used with half precision it returns the half precision delta position state update
             /// which will not be the full position.
             /// To get a NettworkTransform's full position, use <see cref="GetSpaceRelativePosition(bool)"/> and
             /// pass true as the parameter.
@@ -661,6 +663,8 @@ public int GetNetworkTick()
             /// <summary>
             /// Serializes this <see cref="NetworkTransformState"/>
             /// </summary>
+            /// <typeparam name="T">The type of the serializer.</typeparam>
+            /// <param name="serializer">The serializer used for reading or writing the state.</param>
             public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
             {
                 // Used to calculate the LastSerializedSize value
@@ -897,7 +901,7 @@ public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReade
                 if (HasScaleChange)
                 {
                     // If we are teleporting (which includes synchronizing) and the associated NetworkObject has a parent
-                    // then we want to serialize the LossyScale since NetworkObject spawn order is not  guaranteed 
+                    // then we want to serialize the LossyScale since NetworkObject spawn order is not  guaranteed
                     if (IsTeleportingNextFrame && IsParented)
                     {
                         serializer.SerializeValue(ref LossyScale);
@@ -1419,9 +1423,8 @@ private bool ShouldSynchronizeHalfFloat(ulong targetClientId)
         /// <remarks>
         /// If a derived class overrides this, then make sure to invoke this base method!
         /// </remarks>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="serializer"></param>
-        /// <param name="targetClientId">the clientId being synchronized (both reading and writing)</param>
+        /// <typeparam name="T">The type of the serializer.</typeparam>
+        /// <param name="serializer">The serializer used for reading or writing the state.</param>
         protected override void OnSynchronize<T>(ref BufferSerializer<T> serializer)
         {
             m_CachedNetworkManager = NetworkManager;
@@ -1575,11 +1578,11 @@ private void TryCommitTransform(ref Transform transformToCommit, bool synchroniz
                     Debug.LogException(ex);
                 }
 
-                // The below is part of assuring we only send a frame synch, when sending unreliable deltas, if 
+                // The below is part of assuring we only send a frame synch, when sending unreliable deltas, if
                 // we have already sent at least one unreliable delta state update. At this point in the callstack,
                 // a delta state update has just been sent in the above UpdateTransformState() call and as long as
                 // we didn't send a frame synch and we are not synchronizing then we know at least one unreliable
-                // delta has been sent. Under this scenario, we should start checking for this instance's alloted 
+                // delta has been sent. Under this scenario, we should start checking for this instance's alloted
                 // frame synch "tick slot". Once we send a frame synch, if no other deltas occur after that
                 // (i.e. the object is at rest) then we will stop sending frame synch's until the object begins
                 // moving, rotating, or scaling again.
@@ -1862,7 +1865,7 @@ private bool ApplyTransformToNetworkStateWithInfo(ref NetworkTransformState netw
 
                         networkState.NetworkDeltaPosition = m_HalfPositionState;
 
-                        // If ownership offset is greater or we are doing an axial synchronization then synchronize the base position 
+                        // If ownership offset is greater or we are doing an axial synchronization then synchronize the base position
                         if ((m_HalfFloatTargetTickOwnership > m_CachedNetworkManager.ServerTime.Tick || isAxisSync) && !networkState.IsTeleportingNextFrame)
                         {
                             networkState.SynchronizeBaseHalfFloat = true;
@@ -2056,6 +2059,10 @@ private bool ApplyTransformToNetworkStateWithInfo(ref NetworkTransformState netw
             return isDirty;
         }
 
+        /// <summary>
+        /// Invoked whenever the transform has been updated.
+        /// This method can be overridden to handle any custom logic that needs to occur after the transform has been updated.
+        /// </summary>
         protected virtual void OnTransformUpdated()
         {
 
@@ -2602,6 +2609,10 @@ protected virtual void OnNetworkTransformStateUpdated(ref NetworkTransformState
 
         }
 
+        /// <summary>
+        /// Invoked just before the transform state is updated.
+        /// This method can be overridden to handle any custom logic that needs to occur before the transform state is updated.
+        /// </summary>
         protected virtual void OnBeforeUpdateTransformState()
         {
 
@@ -2816,6 +2827,12 @@ public override void OnGainedOwnership()
             base.OnGainedOwnership();
         }
 
+        /// <summary>
+        /// Invoked when the ownership of the <see cref="NetworkObject"/> changes.
+        /// This method handles reinitialization when the local client gains or loses ownership of the <see cref="NetworkObject"/>.
+        /// </summary>
+        /// <param name="previous">The client ID of the previous owner.</param>
+        /// <param name="current">The client ID of the new owner.</param>
         protected override void OnOwnershipChanged(ulong previous, ulong current)
         {
             // If we were the previous owner or the newly assigned owner then reinitialize
@@ -2842,7 +2859,7 @@ protected virtual void OnInitialize(ref NetworkTransformState replicatedState)
         /// This method is only invoked by the owner
         /// Use: OnInitialize(ref NetworkTransformState replicatedState) to be notified on all instances
         /// </summary>
-        /// <param name="replicatedState"></param>
+        /// <param name="replicatedState">The current <see cref="NetworkVariable{NetworkTransformState}"/> after initializing.</param>
         protected virtual void OnInitialize(ref NetworkVariable<NetworkTransformState> replicatedState)
         {
 
@@ -2851,9 +2868,9 @@ protected virtual void OnInitialize(ref NetworkVariable<NetworkTransformState> r
         private int m_HalfFloatTargetTickOwnership;
 
         /// <summary>
-        /// The internal initialzation method to allow for internal API adjustments
+        /// The internal initialization method to allow for internal API adjustments
         /// </summary>
-        /// <param name="isOwnershipChange"></param>
+        /// <param name="isOwnershipChange">Indicates whether the initialization is due to an ownership change.</param>
         private void InternalInitialization(bool isOwnershipChange = false)
         {
             if (!IsSpawned)
@@ -2956,11 +2973,11 @@ public override void OnNetworkObjectParentChanged(NetworkObject parentNetworkObj
         /// The parameters are broken up into pos / rot / scale on purpose so that the caller can perturb
         ///  just the desired one(s)
         /// </summary>
-        /// <param name="posIn"></param> new position to move to.  Can be null
-        /// <param name="rotIn"></param> new rotation to rotate to.  Can be null
+        /// <param name="posIn">new position to move to. Can be null.</param>
+        /// <param name="rotIn">new rotation to rotate to. Can be null.</param>
         /// <param name="scaleIn">new scale to scale to. Can be null</param>
         /// <param name="teleportDisabled">When true (the default) the <see cref="NetworkObject"/> will not be teleported and, if enabled, will interpolate. When false the <see cref="NetworkObject"/> will teleport/apply the parameters provided immediately.</param>
-        /// <exception cref="Exception"></exception>
+        /// <exception cref="Exception">Thrown when the function is called on non-spawned object or, when it's called without proper authority</exception>
         public void SetState(Vector3? posIn = null, Quaternion? rotIn = null, Vector3? scaleIn = null, bool teleportDisabled = true)
         {
             if (!IsSpawned)
@@ -3023,7 +3040,7 @@ private void SetStateInternal(Vector3 pos, Quaternion rot, Vector3 scale, bool s
 
             var transformToCommit = transform;
 
-            // Explicit set states are cumulative during a fractional tick period of time (i.e. each SetState invocation will 
+            // Explicit set states are cumulative during a fractional tick period of time (i.e. each SetState invocation will
             // update the axial deltas to whatever changes are applied). As such, we need to preserve the dirty and explicit
             // state flags.
             var stateWasDirty = m_LocalAuthoritativeNetworkState.IsDirty;
@@ -3111,7 +3128,9 @@ private void UpdateInterpolation()
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// This method is called once per frame.
+        /// </summary>
         /// <remarks>
         /// If you override this method, be sure that:
         /// - Non-authority always invokes this base class method.
@@ -3134,10 +3153,10 @@ protected virtual void Update()
         /// <summary>
         /// Teleport the transform to the given values without interpolating
         /// </summary>
-        /// <param name="newPosition"></param> new position to move to.
-        /// <param name="newRotation"></param> new rotation to rotate to.
+        /// <param name="newPosition">new position to move to.</param>
+        /// <param name="newRotation">new rotation to rotate to.</param>
         /// <param name="newScale">new scale to scale to.</param>
-        /// <exception cref="Exception"></exception>
+        /// <exception cref="Exception">Thrown if teleporting is attempted on a non-authoritative side.</exception>
         public void Teleport(Vector3 newPosition, Quaternion newRotation, Vector3 newScale)
         {
             if (!CanCommitToTransform)