From f9ffd2538f3bf300e8f751258a6129fb780b5b0a Mon Sep 17 00:00:00 2001
From: Justin Clark-Casey (justincc)
Date: Wed, 12 Oct 2011 19:22:30 +0100
Subject: Improve some method doc for LLUDPClient, LLUDPServer and
 UnackedPacketCollection

---
 .../Region/ClientStack/Linden/UDP/LLUDPClient.cs   | 22 +++++++++++++++-------
 .../Region/ClientStack/Linden/UDP/LLUDPServer.cs   | 17 +++++++++++++----
 .../Linden/UDP/UnackedPacketCollection.cs          | 17 +++++++++++------
 3 files changed, 39 insertions(+), 17 deletions(-)

(limited to 'OpenSim')

diff --git a/OpenSim/Region/ClientStack/Linden/UDP/LLUDPClient.cs b/OpenSim/Region/ClientStack/Linden/UDP/LLUDPClient.cs
index ca5501d..31cc515 100644
--- a/OpenSim/Region/ClientStack/Linden/UDP/LLUDPClient.cs
+++ b/OpenSim/Region/ClientStack/Linden/UDP/LLUDPClient.cs
@@ -169,7 +169,16 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// <param name="circuitCode">Circuit code for this connection</param>
         /// <param name="agentID">AgentID for the connected agent</param>
         /// <param name="remoteEndPoint">Remote endpoint for this connection</param>
-        public LLUDPClient(LLUDPServer server, ThrottleRates rates, TokenBucket parentThrottle, uint circuitCode, UUID agentID, IPEndPoint remoteEndPoint, int defaultRTO, int maxRTO)
+        /// <param name="defaultRTO">
+        /// Default retransmission timeout for unacked packets.  The RTO will never drop
+        /// beyond this number.
+        /// </param>
+        /// <param name="maxRTO">
+        /// The maximum retransmission timeout for unacked packets.  The RTO will never exceed this number.
+        /// </param>
+        public LLUDPClient(
+            LLUDPServer server, ThrottleRates rates, TokenBucket parentThrottle, uint circuitCode, UUID agentID,
+            IPEndPoint remoteEndPoint, int defaultRTO, int maxRTO)
         {
             AgentID = agentID;
             RemoteEndPoint = remoteEndPoint;
@@ -197,7 +206,7 @@ namespace OpenSim.Region.ClientStack.LindenUDP
                 m_throttleCategories[i] = new TokenBucket(m_throttleCategory, rates.GetRate(type));
             }
 
-            // Default the retransmission timeout to three seconds
+            // Default the retransmission timeout to one second
             RTO = m_defaultRTO;
 
             // Initialize this to a sane value to prevent early disconnects
@@ -262,9 +271,9 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// <summary>
         /// Return statistics information about client packet queues.
         /// </summary>
-        /// 
+        /// <remarks>
         /// FIXME: This should really be done in a more sensible manner rather than sending back a formatted string.
-        /// 
+        /// </remarks>
         /// <returns></returns>
         public string GetStats()
         {
@@ -606,8 +615,7 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// Does an early check to see if this queue empty callback is already
         /// running, then asynchronously firing the event
         /// </summary>
-        /// <param name="throttleIndex">Throttle category to fire the callback
-        /// for</param>
+        /// <param name="categories">Throttle categories to fire the callback for</param>
         private void BeginFireQueueEmpty(ThrottleOutPacketTypeFlags categories)
         {
             if (m_nextOnQueueEmpty != 0 && (Environment.TickCount & Int32.MaxValue) >= m_nextOnQueueEmpty)
@@ -694,4 +702,4 @@ namespace OpenSim.Region.ClientStack.LindenUDP
             }
         }
     }
-}
+}
\ No newline at end of file
diff --git a/OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs b/OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs
index 304efe6..ccad241 100644
--- a/OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs
+++ b/OpenSim/Region/ClientStack/Linden/UDP/LLUDPServer.cs
@@ -324,7 +324,12 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// <param name="packet"></param>
         /// <param name="category"></param>
         /// <param name="allowSplitting"></param>
-        public void SendPacket(LLUDPClient udpClient, Packet packet, ThrottleOutPacketType category, bool allowSplitting, UnackedPacketMethod method)
+        /// <param name="method">
+        /// The method to call if the packet is not acked by the client.  If null, then a standard
+        /// resend of the packet is done.
+        /// </param>
+        public void SendPacket(
+            LLUDPClient udpClient, Packet packet, ThrottleOutPacketType category, bool allowSplitting, UnackedPacketMethod method)
         {
             // CoarseLocationUpdate packets cannot be split in an automated way
             if (packet.Type == PacketType.CoarseLocationUpdate && allowSplitting)
@@ -357,8 +362,13 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// <param name="udpClient"></param>
         /// <param name="data"></param>
         /// <param name="type"></param>
-        /// <param name="category"></param>        
-        public void SendPacketData(LLUDPClient udpClient, byte[] data, PacketType type, ThrottleOutPacketType category, UnackedPacketMethod method)
+        /// <param name="category"></param>
+        /// <param name="method">
+        /// The method to call if the packet is not acked by the client.  If null, then a standard
+        /// resend of the packet is done.
+        /// </param>
+        public void SendPacketData(
+            LLUDPClient udpClient, byte[] data, PacketType type, ThrottleOutPacketType category, UnackedPacketMethod method)
         {
             int dataLength = data.Length;
             bool doZerocode = (data[0] & Helpers.MSG_ZEROCODED) != 0;
@@ -1100,7 +1110,6 @@ namespace OpenSim.Region.ClientStack.LindenUDP
                 {
                     m_log.Error("[LLUDPSERVER]: OutgoingPacketHandler loop threw an exception: " + ex.Message, ex);
                 }
-
             }
 
             Watchdog.RemoveThread();
diff --git a/OpenSim/Region/ClientStack/Linden/UDP/UnackedPacketCollection.cs b/OpenSim/Region/ClientStack/Linden/UDP/UnackedPacketCollection.cs
index 793aefe..6b1d7d2 100644
--- a/OpenSim/Region/ClientStack/Linden/UDP/UnackedPacketCollection.cs
+++ b/OpenSim/Region/ClientStack/Linden/UDP/UnackedPacketCollection.cs
@@ -118,12 +118,17 @@ namespace OpenSim.Region.ClientStack.LindenUDP
         /// Returns a list of all of the packets with a TickCount older than
         /// the specified timeout
         /// </summary>
+        /// <remarks>
+        /// This function is not thread safe, and cannot be called
+        /// multiple times concurrently
+        /// </remarks>
         /// <param name="timeoutMS">Number of ticks (milliseconds) before a
-        /// packet is considered expired</param>
-        /// <returns>A list of all expired packets according to the given
-        /// expiration timeout</returns>
-        /// <remarks>This function is not thread safe, and cannot be called
-        /// multiple times concurrently</remarks>
+        /// packet is considered expired
+        /// </param>
+        /// <returns>
+        /// A list of all expired packets according to the given
+        /// expiration timeout
+        /// </returns>
         public List<OutgoingPacket> GetExpiredPackets(int timeoutMS)
         {
             ProcessQueues();
@@ -216,4 +221,4 @@ namespace OpenSim.Region.ClientStack.LindenUDP
             }
         }
     }
-}
+}
\ No newline at end of file
-- 
cgit v1.1