Transport: xml comments cleanup

Assets/Mirror/Runtime/Transport/Transport.cs

@@ -30,61 +30,31 @@ namespace Mirror
     /// <summary>Abstract transport layer component</summary>
     public abstract class Transport : MonoBehaviour
     {
-        /// <summary>
+        /// <summary>The current transport used by Mirror.</summary>
-        /// The current transport used by Mirror.
-        /// </summary>
         public static Transport activeTransport;
 
-        /// <summary>
+        /// <summary>Is this transport available in the current platform?</summary>
-        /// Is this transport available in the current platform?
-        /// <para>Some transports might only be available in mobile</para>
-        /// <para>Many will not work in webgl</para>
-        /// <para>Example usage: return Application.platform == RuntimePlatform.WebGLPlayer</para>
-        /// </summary>
-        /// <returns>True if this transport works in the current platform</returns>
         public abstract bool Available();
 
-        #region Client
+        /// <summary>Called by Transport when the client connected to the server.</summary>
-        /// <summary>
-        /// Notify subscribers when this client establish a successful connection to the server
-        /// <para>callback()</para>
-        /// </summary>
         public Action OnClientConnected = () => Debug.LogWarning("OnClientConnected called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when the client received a message from the server.</summary>
-        /// Notify subscribers when this client receive data from the server
-        /// <para>callback(ArraySegment&lt;byte&gt; data, int channel)</para>
-        /// </summary>
         public Action<ArraySegment<byte>, int> OnClientDataReceived = (data, channel) => Debug.LogWarning("OnClientDataReceived called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when the client encountered an error.</summary>
-        /// Notify subscribers when this client encounters an error communicating with the server
-        /// <para>callback(Exception e)</para>
-        /// </summary>
         public Action<Exception> OnClientError = (error) => Debug.LogWarning("OnClientError called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when the client disconnected from the server.</summary>
-        /// Notify subscribers when this client disconnects from the server
-        /// <para>callback()</para>
-        /// </summary>
         public Action OnClientDisconnected = () => Debug.LogWarning("OnClientDisconnected called with no handler");
 
-        /// <summary>
+        /// <summary>True if the client is currently connected to the server.</summary>
-        /// Determines if we are currently connected to the server
-        /// </summary>
-        /// <returns>True if a connection has been established to the server</returns>
         public abstract bool ClientConnected();
 
-        /// <summary>
+        /// <summary>Connects the client to the server at the address.</summary>
-        /// Establish a connection to a server
-        /// </summary>
-        /// <param name="address">The IP address or FQDN of the server we are trying to connect to</param>
         public abstract void ClientConnect(string address);
 
-        /// <summary>
+        /// <summary>Connects the client to the server at the Uri.</summary>
-        /// Establish a connection to a server
-        /// </summary>
-        /// <param name="uri">The address of the server we are trying to connect to</param>
         public virtual void ClientConnect(Uri uri)
         {
             // By default, to keep backwards compatibility, just connect to the host
@@ -92,119 +62,61 @@ public virtual void ClientConnect(Uri uri)
             ClientConnect(uri.Host);
         }
 
-        /// <summary>
+        /// <summary>Sends a message to the server over the given channel.</summary>
-        /// Send data to the server
+        // The ArraySegment is only valid until returning. Copy if needed.
-        /// </summary>
-        /// <param name="channelId">The channel to use.  0 is the default channel,
-        /// but some transports might want to provide unreliable, encrypted, compressed, or any other feature
-        /// as new channels</param>
-        /// <param name="segment">The data to send to the server. Will be recycled after returning, so either use it directly or copy it internally. This allows for allocation-free sends!</param>
         public abstract void ClientSend(int channelId, ArraySegment<byte> segment);
 
-        /// <summary>
+        /// <summary>Disconnects the client from the server</summary>
-        /// Disconnect this client from the server
-        /// </summary>
         public abstract void ClientDisconnect();
 
-        #endregion
+        /// <summary>Returns server address as Uri.</summary>
-
+        // Useful for NetworkDiscovery.
-        #region Server
-
-
-        /// <summary>
-        /// Retrieves the address of this server.
-        /// Useful for network discovery
-        /// </summary>
-        /// <returns>the url at which this server can be reached</returns>
         public abstract Uri ServerUri();
 
-        /// <summary>
+        /// <summary>Called by Transport when a new client connected to the server.</summary>
-        /// Notify subscribers when a client connects to this server
-        /// <para>callback(int connId)</para>
-        /// </summary>
         public Action<int> OnServerConnected = (connId) => Debug.LogWarning("OnServerConnected called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when the server received a message from a client.</summary>
-        /// Notify subscribers when this server receives data from the client
-        /// <para>callback(int connId, ArraySegment&lt;byte&gt; data, int channel)</para>
-        /// </summary>
         public Action<int, ArraySegment<byte>, int> OnServerDataReceived = (connId, data, channel) => Debug.LogWarning("OnServerDataReceived called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when a server's connection encountered a problem.</summary>
-        /// Notify subscribers when this server has some problem communicating with the client
-        /// <para>callback(int connId, Exception e)</para>
-        /// </summary>
         public Action<int, Exception> OnServerError = (connId, error) => Debug.LogWarning("OnServerError called with no handler");
 
-        /// <summary>
+        /// <summary>Called by Transport when a client disconnected from the server.</summary>
-        /// Notify subscribers when a client disconnects from this server
-        /// <para>callback(int connId)</para>
-        /// </summary>
         public Action<int> OnServerDisconnected = (connId) => Debug.LogWarning("OnServerDisconnected called with no handler");
 
-        /// <summary>
+        /// <summary>True if the server is currently listening for connections.</summary>
-        /// Determines if the server is up and running
-        /// </summary>
-        /// <returns>true if the transport is ready for connections from clients</returns>
         public abstract bool ServerActive();
 
-        /// <summary>
+        /// <summary>Start listening for connections.</summary>
-        /// Start listening for clients
-        /// </summary>
         public abstract void ServerStart();
 
-        /// <summary>
+        /// <summary>Send a message to a client over the given channel.</summary>
-        /// Send data to a client.
-        /// </summary>
-        /// <param name="connectionId">The client connection id to send the data to</param>
-        /// <param name="channelId">The channel to be used.  Transports can use channels to implement
-        /// other features such as unreliable, encryption, compression, etc...</param>
-        /// <param name="data"></param>
         public abstract void ServerSend(int connectionId, int channelId, ArraySegment<byte> segment);
 
-        /// <summary>
+        /// <summary>Disconnect a client from the server.</summary>
-        /// Disconnect a client from this server.  Useful to kick people out.
-        /// </summary>
-        /// <param name="connectionId">the id of the client to disconnect</param>
         public abstract void ServerDisconnect(int connectionId);
 
-        /// <summary>
+        /// <summary>Get a client's address on the server.</summary>
-        /// Get the client address
+        // Can be useful for Game Master IP bans etc.
-        /// </summary>
-        /// <param name="connectionId">id of the client</param>
-        /// <returns>address of the client</returns>
         public abstract string ServerGetClientAddress(int connectionId);
 
-        /// <summary>
+        /// <summary>Stop listening and disconnect all connections.</summary>
-        /// Stop listening for clients and disconnect all existing clients
-        /// </summary>
         public abstract void ServerStop();
 
-        #endregion
+        /// <summary>Maximum message size for the given channel.</summary>
-
+        // Different channels often have different sizes, ranging from MTU to
-        /// <summary>
+        // several megabytes.
-        /// The maximum packet size for a given channel.  Unreliable transports
+        //
-        /// usually can only deliver small packets. Reliable fragmented channels
+        // Needs to return a value at all times, even if the Transport isn't
-        /// can usually deliver large ones.
+        // running or available because it's needed for initializations.
-        ///
-        /// GetMaxPacketSize needs to return a value at all times. Even if the
-        /// Transport isn't running, or isn't Available(). This is because
-        /// Fallback and Multiplex transports need to find the smallest possible
-        /// packet size at runtime.
-        /// </summary>
-        /// <param name="channelId">channel id</param>
-        /// <returns>the size in bytes that can be sent via the provided channel</returns>
         public abstract int GetMaxPacketSize(int channelId = Channels.Reliable);
 
-        /// <summary>
+        /// <summary>Maximum batch(!) size for the given c hannel.</summary>
-        /// The maximum batch(!) size for a given channel.
+        // Uses GetMaxPacketSize by default.
-        /// Uses GetMaxPacketSize by default.
+        // Some transports like kcp support large max packet sizes which should
-        /// Some transports like kcp support large max packet sizes which should
+        // not be used for batching all the time because they end up being too
-        /// not be used for batching all the time because they end up being too
+        // slow (head of line blocking etc.).
-        /// slow (head of line blocking etc.).
-        /// </summary>
-        /// <param name="channelId">channel id</param>
-        /// <returns>the size in bytes that should be batched via the provided channel</returns>
         public virtual int GetMaxBatchSize(int channelId) =>
             GetMaxPacketSize(channelId);
 
@@ -242,15 +154,10 @@ public virtual void ServerEarlyUpdate() {}
         public virtual void ClientLateUpdate() {}
         public virtual void ServerLateUpdate() {}
 
-        /// <summary>
+        /// <summary>Shut down the transport, both as client and server</summary>
-        /// Shut down the transport, both as client and server
-        /// </summary>
         public abstract void Shutdown();
 
-        /// <summary>
+        /// <summary>Called by Unity when quitting. Inheriting Transports should call base for proper Shutdown.</summary>
-        /// called when quitting the application by closing the window / pressing stop in the editor
-        /// <para>virtual so that inheriting classes' OnApplicationQuit() can call base.OnApplicationQuit() too</para>
-        /// </summary>
         public virtual void OnApplicationQuit()
         {
             // stop transport (e.g. to shut down threads)