fix: API Audit for missing XML documentation [MTT-3881] (#2026)

Author: NoelStephensUnity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -18,7 +18,7 @@ Additional documentation and release notes are available at [Multiplayer Documen
 ### Changed
 
 - Updated `UnityTransport` dependency on `com.unity.transport` to 1.1.0. (#2025)
-- (API Breaking) `ConnectionApprovalCallback` is no longer an `event` and will not allow more than 1 handler registered at a time. Also, `ConnectionApprovalCallback` is now a `Func<>` taking `ConnectionApprovalRequest` in and returning `ConnectionApprovalResponse` back out (#1972)
+- (API Breaking) `ConnectionApprovalCallback` is no longer an `event` and will not allow more than 1 handler registered at a time. Also, `ConnectionApprovalCallback` is now an `Action<>` taking a `ConnectionApprovalRequest` and a `ConnectionApprovalResponse` that the client code must fill (#1972) (#2002)
 
 ### Removed
 

com.unity.netcode.gameobjects/Components/Interpolator/BufferedLinearInterpolator.cs

@@ -8,6 +8,7 @@ namespace Unity.Netcode
     /// Solves for incoming values that are jittered
     /// Partially solves for message loss. Unclamped lerping helps hide this, but not completely
     /// </summary>
+    /// <typeparam name="T">The type of interpolated value</typeparam>
     public abstract class BufferedLinearInterpolator<T> where T : struct
     {
         internal float MaxInterpolationBound = 3.0f;
@@ -24,7 +25,7 @@ public BufferedItem(T item, double timeSent)
         }
 
         /// <summary>
-        /// There’s two factors affecting interpolation: buffering (set in NetworkManager’s NetworkTimeSystem) and interpolation time, which is the amount of time it’ll take to reach the target. This is to affect the second one.
+        /// There's two factors affecting interpolation: buffering (set in NetworkManager's NetworkTimeSystem) and interpolation time, which is the amount of time it'll take to reach the target. This is to affect the second one.
         /// </summary>
         public float MaximumInterpolationTime = 0.1f;
 
@@ -73,7 +74,7 @@ public BufferedItem(T item, double timeSent)
         private bool InvalidState => m_Buffer.Count == 0 && m_LifetimeConsumedCount == 0;
 
         /// <summary>
-        /// Resets Interpolator to initial state
+        /// Resets interpolator to initial state
         /// </summary>
         public void Clear()
         {
@@ -85,6 +86,8 @@ public void Clear()
         /// <summary>
         /// Teleports current interpolation value to targetValue.
         /// </summary>
+        /// <param name="targetValue">The target value to teleport instantly</param>
+        /// <param name="serverTime">The current server time</param>
         public void ResetTo(T targetValue, double serverTime)
         {
             m_LifetimeConsumedCount = 1;
@@ -159,6 +162,7 @@ private void TryConsumeFromBuffer(double renderTime, double serverTime)
         /// </summary>
         /// <param name="deltaTime">time since call</param>
         /// <param name="serverTime">current server time</param>
+        /// <returns>The newly interpolated value of type 'T'</returns>
         public T Update(float deltaTime, NetworkTime serverTime)
         {
             return Update(deltaTime, serverTime.TimeTicksAgo(1).Time, serverTime.Time);
@@ -170,6 +174,7 @@ public T Update(float deltaTime, NetworkTime serverTime)
         /// <param name="deltaTime">time since last call</param>
         /// <param name="renderTime">our current time</param>
         /// <param name="serverTime">current server time</param>
+        /// <returns>The newly interpolated value of type 'T'</returns>
         public T Update(float deltaTime, double renderTime, double serverTime)
         {
             TryConsumeFromBuffer(renderTime, serverTime);
@@ -222,6 +227,8 @@ public T Update(float deltaTime, double renderTime, double serverTime)
         /// <summary>
         /// Add measurements to be used during interpolation. These will be buffered before being made available to be displayed as "latest value".
         /// </summary>
+        /// <param name="newMeasurement">The new measurement value to use</param>
+        /// <param name="sentTime">The time to record for measurement</param>
         public void AddMeasurement(T newMeasurement, double sentTime)
         {
             m_NbItemsReceivedThisFrame++;
@@ -251,6 +258,7 @@ public void AddMeasurement(T newMeasurement, double sentTime)
         /// <summary>
         /// Gets latest value from the interpolator. This is updated every update as time goes by.
         /// </summary>
+        /// <returns>The current interpolated value of type 'T'</returns>
         public T GetInterpolatedValue()
         {
             return m_CurrentInterpValue;
@@ -259,33 +267,54 @@ public T GetInterpolatedValue()
         /// <summary>
         /// Method to override and adapted to the generic type. This assumes interpolation for that value will be clamped.
         /// </summary>
+        /// <param name="start">The start value (min)</param>
+        /// <param name="end">The end value (max)</param>
+        /// <param name="time">The time value used to interpolate between start and end values (pos)</param>
+        /// <returns>The interpolated value</returns>
         protected abstract T Interpolate(T start, T end, float time);
+
         /// <summary>
         /// Method to override and adapted to the generic type. This assumes interpolation for that value will not be clamped.
         /// </summary>
+        /// <param name="start">The start value (min)</param>
+        /// <param name="end">The end value (max)</param>
+        /// <param name="time">The time value used to interpolate between start and end values (pos)</param>
+        /// <returns>The interpolated value</returns>
         protected abstract T InterpolateUnclamped(T start, T end, float time);
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// This is a buffered linear interpolator for a <see cref="float"/> type value
+    /// </remarks>
     public class BufferedLinearInterpolatorFloat : BufferedLinearInterpolator<float>
     {
+        /// <inheritdoc />
         protected override float InterpolateUnclamped(float start, float end, float time)
         {
             return Mathf.LerpUnclamped(start, end, time);
         }
 
+        /// <inheritdoc />
         protected override float Interpolate(float start, float end, float time)
         {
             return Mathf.Lerp(start, end, time);
         }
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// This is a buffered linear interpolator for a <see cref="Quaternion"/> type value
+    /// </remarks>
     public class BufferedLinearInterpolatorQuaternion : BufferedLinearInterpolator<Quaternion>
     {
+        /// <inheritdoc />
         protected override Quaternion InterpolateUnclamped(Quaternion start, Quaternion end, float time)
         {
             return Quaternion.SlerpUnclamped(start, end, time);
         }
 
+        /// <inheritdoc />
         protected override Quaternion Interpolate(Quaternion start, Quaternion end, float time)
         {
             return Quaternion.SlerpUnclamped(start, end, time);

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

@@ -37,6 +37,7 @@ private void FlushMessages()
             m_SendTriggerUpdates.Clear();
         }
 
+        /// <inheritdoc />
         public void NetworkUpdate(NetworkUpdateStage updateStage)
         {
             switch (updateStage)

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

@@ -5,20 +5,46 @@
 namespace Unity.Netcode.Components
 {
     /// <summary>
-    /// A component for syncing transforms
+    /// A component for syncing transforms.
     /// NetworkTransform will read the underlying transform and replicate it to clients.
-    /// The replicated value will be automatically be interpolated (if active) and applied to the underlying GameObject's transform
+    /// The replicated value will be automatically be interpolated (if active) and applied to the underlying GameObject's transform.
     /// </summary>
     [DisallowMultipleComponent]
     [AddComponentMenu("Netcode/" + nameof(NetworkTransform))]
     [DefaultExecutionOrder(100000)] // this is needed to catch the update time after the transform was updated by user scripts
     public class NetworkTransform : NetworkBehaviour
     {
+        /// <summary>
+        /// The default position change threshold value.
+        /// Any changes above this threshold will be replicated.
+        /// </summary>
         public const float PositionThresholdDefault = 0.001f;
+
+        /// <summary>
+        /// The default rotation angle change threshold value.
+        /// Any changes above this threshold will be replicated.
+        /// </summary>
         public const float RotAngleThresholdDefault = 0.01f;
+
+        /// <summary>
+        /// The default scale change threshold value.
+        /// Any changes above this threshold will be replicated.
+        /// </summary>
         public const float ScaleThresholdDefault = 0.01f;
 
+        /// <summary>
+        /// The handler delegate type that takes client requested changes and returns resulting changes handled by the server.
+        /// </summary>
+        /// <param name="pos">The position requested by the client.</param>
+        /// <param name="rot">The rotation requested by the client.</param>
+        /// <param name="scale">The scale requested by the client.</param>
+        /// <returns>The resulting position, rotation and scale changes after handling.</returns>
         public delegate (Vector3 pos, Quaternion rotOut, Vector3 scale) OnClientRequestChangeDelegate(Vector3 pos, Quaternion rot, Vector3 scale);
+
+        /// <summary>
+        /// The handler that gets invoked when server receives a change from a client.
+        /// This handler would be useful for server to modify pos/rot/scale before applying client's request.
+        /// </summary>
         public OnClientRequestChangeDelegate OnClientRequestChange;
 
         internal struct NetworkTransformState : INetworkSerializable
@@ -244,15 +270,62 @@ public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReade
             }
         }
 
-        public bool SyncPositionX = true, SyncPositionY = true, SyncPositionZ = true;
-        public bool SyncRotAngleX = true, SyncRotAngleY = true, SyncRotAngleZ = true;
-        public bool SyncScaleX = true, SyncScaleY = true, SyncScaleZ = true;
+        /// <summary>
+        /// Whether or not x component of position will be replicated
+        /// </summary>
+        public bool SyncPositionX = true;
+        /// <summary>
+        /// Whether or not y component of position will be replicated
+        /// </summary>
+        public bool SyncPositionY = true;
+        /// <summary>
+        /// Whether or not z component of position will be replicated
+        /// </summary>
+        public bool SyncPositionZ = true;
+        /// <summary>
+        /// Whether or not x component of rotation will be replicated
+        /// </summary>
+        public bool SyncRotAngleX = true;
+        /// <summary>
+        /// Whether or not y component of rotation will be replicated
+        /// </summary>
+        public bool SyncRotAngleY = true;
+        /// <summary>
+        /// Whether or not z component of rotation will be replicated
+        /// </summary>
+        public bool SyncRotAngleZ = true;
+        /// <summary>
+        /// Whether or not x component of scale will be replicated
+        /// </summary>
+        public bool SyncScaleX = true;
+        /// <summary>
+        /// Whether or not y component of scale will be replicated
+        /// </summary>
+        public bool SyncScaleY = true;
+        /// <summary>
+        /// Whether or not z component of scale will be replicated
+        /// </summary>
+        public bool SyncScaleZ = true;
 
+        /// <summary>
+        /// The current position threshold value
+        /// Any changes to the position that exceeds the current threshold value will be replicated
+        /// </summary>
         public float PositionThreshold = PositionThresholdDefault;
 
+        /// <summary>
+        /// The current rotation threshold value
+        /// Any changes to the rotation that exceeds the current threshold value will be replicated
+        /// Minimum Value: 0.001
+        /// Maximum Value: 360.0
+        /// </summary>
         [Range(0.001f, 360.0f)]
         public float RotAngleThreshold = RotAngleThresholdDefault;
 
+        /// <summary>
+        /// The current scale threshold value
+        /// Any changes to the scale that exceeds the current threshold value will be replicated
+        /// </summary>
         public float ScaleThreshold = ScaleThresholdDefault;
 
         /// <summary>
@@ -265,6 +338,10 @@ public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReade
         public bool InLocalSpace = false;
         private bool m_LastInterpolateLocal = false; // was the last frame local
 
+        /// <summary>
+        /// When enabled (default) interpolation is applied and when disabled no interpolation is applied
+        /// Note: can be changed during runtime.
+        /// </summary>
         public bool Interpolate = true;
         private bool m_LastInterpolate = true; // was the last frame interpolated
 
@@ -276,7 +353,17 @@ public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReade
         /// </summary>
         // This is public to make sure that users don't depend on this IsClient && IsOwner check in their code. If this logic changes in the future, we can make it invisible here
         public bool CanCommitToTransform { get; protected set; }
+
+        /// <summary>
+        /// Internally used by <see cref="NetworkTransform"/> to keep track of whether this <see cref="NetworkBehaviour"/> derived class instance
+        /// was instantiated on the server side or not.
+        /// </summary>
         protected bool m_CachedIsServer;
+
+        /// <summary>
+        /// Internally used by <see cref="NetworkTransform"/> to keep track of the <see cref="NetworkManager"/> instance assigned to this
+        /// this <see cref="NetworkBehaviour"/> derived class instance.
+        /// </summary>
         protected NetworkManager m_CachedNetworkManager;
 
         private readonly NetworkVariable<NetworkTransformState> m_ReplicatedNetworkState = new NetworkVariable<NetworkTransformState>(new NetworkTransformState());
@@ -716,6 +803,13 @@ private void OnNetworkStateChanged(NetworkTransformState oldState, NetworkTransf
             }
         }
 
+        /// <summary>
+        /// Will set the maximum interpolation boundary for the interpolators of this <see cref="NetworkTransform"/> instance.
+        /// This value roughly translates to the maximum value of 't' in <see cref="Mathf.Lerp(float, float, float)"/> and
+        /// <see cref="Mathf.LerpUnclamped(float, float, float)"/> for all transform elements being monitored by
+        /// <see cref="NetworkTransform"/> (i.e. Position, Rotation, and Scale)
+        /// </summary>
+        /// <param name="maxInterpolationBound">Maximum time boundary that can be used in a frame when interpolating between two values</param>
         public void SetMaxInterpolationBound(float maxInterpolationBound)
         {
             m_PositionXInterpolator.MaxInterpolationBound = maxInterpolationBound;
@@ -750,6 +844,8 @@ private void Awake()
             }
         }
 
+
+        /// <inheritdoc/>
         public override void OnNetworkSpawn()
         {
             // must set up m_Transform in OnNetworkSpawn because it's possible an object spawns but is disabled
@@ -773,16 +869,19 @@ public override void OnNetworkSpawn()
             Initialize();
         }
 
+        /// <inheritdoc/>
         public override void OnNetworkDespawn()
         {
             m_ReplicatedNetworkState.OnValueChanged -= OnNetworkStateChanged;
         }
 
+        /// <inheritdoc/>
         public override void OnGainedOwnership()
         {
             Initialize();
         }
 
+        /// <inheritdoc/>
         public override void OnLostOwnership()
         {
             Initialize();
@@ -850,8 +949,7 @@ public void SetState(Vector3? posIn = null, Quaternion? rotIn = null, Vector3? s
         [ServerRpc]
         private void SetStateServerRpc(Vector3 pos, Quaternion rot, Vector3 scale, bool shouldTeleport)
         {
-            // server has received this RPC request to move change transform.  Give the server a chance to modify or
-            //  even reject the move
+            // server has received this RPC request to move change transform. give the server a chance to modify or even reject the move
             if (OnClientRequestChange != null)
             {
                 (pos, rot, scale) = OnClientRequestChange(pos, rot, scale);
@@ -862,8 +960,9 @@ private void SetStateServerRpc(Vector3 pos, Quaternion rot, Vector3 scale, bool
             m_LocalAuthoritativeNetworkState.IsTeleportingNextFrame = shouldTeleport;
         }
 
-        // todo this is currently in update, to be able to catch any transform changes. A FixedUpdate mode could be added to be less intense, but it'd be
+        // todo: this is currently in update, to be able to catch any transform changes. A FixedUpdate mode could be added to be less intense, but it'd be
         // conditional to users only making transform update changes in FixedUpdate.
+        /// <inheritdoc/>
         protected virtual void Update()
         {
             if (!IsSpawned)
@@ -921,6 +1020,10 @@ protected virtual void Update()
         /// <summary>
         /// Teleports 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="newScale">new scale to scale to.</param>
+        /// <exception cref="Exception"></exception>
         public void Teleport(Vector3 newPosition, Quaternion newRotation, Vector3 newScale)
         {
             if (!CanCommitToTransform)
@@ -945,6 +1048,7 @@ public void Teleport(Vector3 newPosition, Quaternion newRotation, Vector3 newSca
         /// <summary>
         /// Override this method and return false to switch to owner authoritative mode
         /// </summary>
+        /// <returns>(<see cref="true"/> or <see cref="false"/>) where when false it runs as owner-client authoritative</returns>
         protected virtual bool OnIsServerAuthoritative()
         {
             return true;

com.unity.netcode.gameobjects/Editor/NetworkBehaviourEditor.cs

@@ -151,6 +151,8 @@ private void RenderNetworkVariableValueType<T>(int index) where T : unmanaged
             }
         }
 
+
+        /// <inheritdoc/>
         public override void OnInspectorGUI()
         {
             if (!m_Initialized)
@@ -230,6 +232,11 @@ private void OnEnable()
 
         internal const string AutoAddNetworkObjectIfNoneExists = "AutoAdd-NetworkObject-When-None-Exist";
 
+        /// <summary>
+        /// Recursively finds the root parent of a <see cref="Transform"/>
+        /// </summary>
+        /// <param name="transform">The current <see cref="Transform"/> we are inspecting for a parent</param>
+        /// <returns>the root parent for the first <see cref="Transform"/> passed into the method</returns>
         public static Transform GetRootParentTransform(Transform transform)
         {
             if (transform.parent == null || transform.parent == transform)
@@ -244,6 +251,8 @@ public static Transform GetRootParentTransform(Transform transform)
         /// does not already have a NetworkObject component.  If not it will notify
         /// the user that NetworkBehaviours require a NetworkObject.
         /// </summary>
+        /// <param name="gameObject"><see cref="GameObject"/> to start checking for a <see cref="NetworkObject"/></param>
+        /// <param name="networkObjectRemoved">used internally</param>
         public static void CheckForNetworkObject(GameObject gameObject, bool networkObjectRemoved = false)
         {
             // If there are no NetworkBehaviours or no gameObject, then exit early