chore: api documentation phase 1 [backport] (#3157)

* update updating XML API documentation for ConnectionEvent and ConnectionEventData. * update Updating XML API documentation for RpcTargetUse. * Update com.unity.netcode.gameobjects/Runtime/Messaging/RpcTargets/RpcTarget.cs Co-authored-by: Emma <[email protected]> * Update com.unity.netcode.gameobjects/Runtime/Messaging/RpcTargets/RpcTarget.cs Co-authored-by: Emma <[email protected]> --------- Co-authored-by: Emma <[email protected]>
Unity-Technologies · Dec 6, 2024 · be7f604 · be7f604
1 parent 6e777f9
commit be7f604
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 1 deletion.
diff --git a/com.unity.netcode.gameobjects/Runtime/Connection/NetworkConnectionManager.cs b/com.unity.netcode.gameobjects/Runtime/Connection/NetworkConnectionManager.cs
@@ -10,15 +10,54 @@
 
 namespace Unity.Netcode
 {
-
+    /// <summary>
+    /// The connection event type set within <see cref="ConnectionEventData"/> to signify the type of connection event notification received.   
+    /// </summary>
+    /// <remarks>
+    /// <see cref="ConnectionEventData"/> is returned as a parameter of the <see cref="NetworkManager.OnConnectionEvent"/> event notification.
+    /// <see cref="ClientConnected"/> and <see cref="ClientDisconnected"/> event types occur on the client-side of the newly connected client and on the server-side. <br />
+    /// <see cref="PeerConnected"/> and <see cref="PeerDisconnected"/> event types occur on connected clients to notify that a new client (peer) has joined/connected.
+    /// </remarks>
     public enum ConnectionEvent
     {
+        /// <summary>
+        /// This event is set on the client-side of the newly connected client and on the server-side.<br />
+        /// </summary>
+        /// <remarks>
+        /// On the newly connected client side, the <see cref="ConnectionEventData.ClientId"/> will be the <see cref="NetworkManager.LocalClientId"/>.<br />
+        /// On the server side, the <see cref="ConnectionEventData.ClientId"/> will be the ID of the client that just connected.
+        /// </remarks>
         ClientConnected,
+        /// <summary>
+        /// This event is set on clients that are already connected to the session.
+        /// </summary>
+        /// <remarks>
+        /// The <see cref="ConnectionEventData.ClientId"/> will be the ID of the client that just connected.
+        /// </remarks>
         PeerConnected,
+        /// <summary>
+        /// This event is set on the client-side of the client that disconnected client and on the server-side.
+        /// </summary>
+        /// <remarks>
+        /// On the disconnected client side, the <see cref="ConnectionEventData.ClientId"/> will be the <see cref="NetworkManager.LocalClientId"/>.<br />
+        /// On the server side, this will be the ID of the client that disconnected.
+        /// </remarks>
         ClientDisconnected,
+        /// <summary>
+        /// This event is set on clients that are already connected to the session.
+        /// </summary>
+        /// <remarks>
+        /// The <see cref="ConnectionEventData.ClientId"/> will be the ID of the client that just disconnected.
+        /// </remarks>
         PeerDisconnected
     }
 
+    /// <summary>
+    /// Returned as a parameter of the <see cref="NetworkManager.OnConnectionEvent"/> event notification.
+    /// </summary>
+    /// <remarks>
+    /// See <see cref="ConnectionEvent"/> for more details on the types of connection events received.
+    /// </remarks>
     public struct ConnectionEventData
     {
         public ConnectionEvent EventType;

diff --git a/com.unity.netcode.gameobjects/Runtime/Messaging/RpcTargets/RpcTarget.cs b/com.unity.netcode.gameobjects/Runtime/Messaging/RpcTargets/RpcTarget.cs
@@ -67,9 +67,28 @@ public enum SendTo
         SpecifiedInParams
     }
 
+    /// <summary>
+    /// This parameter configures a performance optimization. This optimization is not valid in all situations.<br />
+    /// Because BaseRpcTarget is a managed type, allocating a new one is expensive, as it puts pressure on the garbage collector.
+    /// </summary>
+    /// <remarks>
+    /// When using a <see cref="Temp"/> allocation type for the RPC target(s):<br />
+    /// You typically don't need to worry about persisting the <see cref="BaseRpcTarget"/> generated.
+    /// When using a <see cref="Persistent"/> allocation type for the RPC target(s): <br />
+    /// You will want to use <see cref="RpcTarget"/>, which returns <see cref="BaseRpcTarget"/>, during <see cref="NetworkBehaviour"/> initialization (i.e. <see cref="NetworkBehaviour.OnNetworkPostSpawn"/>) and it to a property.<br />
+    /// Then, When invoking the RPC, you would use your <see cref="BaseRpcTarget"/> which is a persisted allocation of a given set of client identifiers.
+    /// !! Important !!<br />
+    /// You will want to invoke <see cref="BaseRpcTarget.Dispose"/> of any persisted properties created via <see cref="RpcTarget"/> when despawning or destroying the associated <see cref="NetworkBehaviour"/> component's <see cref="NetworkObject"/>. Not doing so will result in small memory leaks.
+    /// </remarks>
     public enum RpcTargetUse
     {
+        /// <summary>
+        /// Creates a temporary <see cref="BaseRpcTarget"/> used for the frame an <see cref="RpcAttribute"/> decorated method is invoked.
+        /// </summary>
         Temp,
+        /// <summary>
+        /// Creates a persisted <see cref="BaseRpcTarget"/> that does not change and will persist until <see cref="BaseRpcTarget.Dispose"/> is called.
+        /// </summary>
         Persistent
     }