fix: API doc fixes from user feedback (#2878)

* Adding missing words for OnDestroy API doc

* Reference pointing to what?

* Improving remarks for OnServerStopped and OnClientStopped

* Updates to summary from review

* Formatting

Author: jabbacakes

com.unity.netcode.gameobjects/Runtime/Core/NetworkBehaviour.cs

@@ -681,7 +681,7 @@ internal void InternalOnGainedOwnership()
         /// <summary>
         /// Invoked on all clients, override this method to be notified of any
         /// ownership changes (even if the instance was niether the previous or
-        /// newly assigned current owner). 
+        /// newly assigned current owner).
         /// </summary>
         /// <param name="previous">the previous owner</param>
         /// <param name="current">the current owner</param>
@@ -1223,9 +1223,9 @@ internal bool Synchronize<T>(ref BufferSerializer<T> serializer, ulong targetCli
 
 
         /// <summary>
-        /// Invoked when the <see cref="GameObject"/> the <see cref="NetworkBehaviour"/> is attached to.
-        /// NOTE:  If you override this, you will want to always invoke this base class version of this
-        /// <see cref="OnDestroy"/> method!!
+        /// Invoked when the <see cref="GameObject"/> the <see cref="NetworkBehaviour"/> is attached to is destroyed.
+        /// NOTE:  If you override this, you should invoke this base class version of this
+        /// <see cref="OnDestroy"/> method.
         /// </summary>
         public virtual void OnDestroy()
         {

com.unity.netcode.gameobjects/Runtime/Core/NetworkManager.cs

@@ -463,20 +463,21 @@ public struct ConnectionApprovalRequest
         public event Action OnServerStarted = null;
 
         /// <summary>
-        /// The callback to invoke once the local client is ready
+        /// The callback to invoke once the local client is ready.
         /// </summary>
         public event Action OnClientStarted = null;
 
         /// <summary>
         /// This callback is invoked once the local server is stopped.
         /// </summary>
+        /// <remarks>The bool parameter will be set to true when stopping a host instance and false when stopping a server instance.</remarks>
         /// <param name="arg1">The first parameter of this event will be set to <see cref="true"/> when stopping a host instance and <see cref="false"/> when stopping a server instance.</param>
         public event Action<bool> OnServerStopped = null;
 
         /// <summary>
-        /// The callback to invoke once the local client stops
+        /// The callback to invoke once the local client stops.
         /// </summary>
-        /// <remarks>The parameter states whether the client was running in host mode</remarks>
+        /// <remarks>The bool parameter will be set to true when stopping a host client and false when stopping a standard client instance.</remarks>
         /// <param name="arg1">The first parameter of this event will be set to <see cref="true"/> when stopping the host client and <see cref="false"/> when stopping a standard client instance.</param>
         public event Action<bool> OnClientStopped = null;
 

com.unity.netcode.gameobjects/Runtime/Serialization/NetworkBehaviourReference.cs

@@ -5,7 +5,9 @@ namespace Unity.Netcode
 {
     /// <summary>
     /// A helper struct for serializing <see cref="NetworkBehaviour"/>s over the network. Can be used in RPCs and <see cref="NetworkVariable{T}"/>.
-    /// Note: network ids get recycled by the NetworkManager after a while. So a reference pointing to
+    /// Network IDs get recycled by the NetworkManager after a while, so using a NetworkBehaviourReference for too long may result in a
+    /// different NetworkBehaviour being returned for the assigned NetworkBehaviourId. NetworkBehaviourReferences are best for short-term
+    /// use when receieved via RPC or custom message, rather than for long-term references to NetworkBehaviours.
     /// </summary>
     public struct NetworkBehaviourReference : INetworkSerializable, IEquatable<NetworkBehaviourReference>
     {