Revize 5b50fe1a

Re #8906 - Client refactor + doc comments (2)

deltarobot-vr/Assets/DeltaRobotVr/Client.cs

@@ -8 +8 @@
 
 namespace DeltaRobotVr
 {
+    
+    /// <summary>
+    /// Singleton class responsible for communication with the Deltarobot server.
+    /// </summary>
     public sealed class Client
     {
         // singleton instance
@@ -63 +67 @@
         private long _curveCounter = 0;
 
         private volatile bool _isConnected;
-        private volatile string _eotMsg = string.Empty;
+        private volatile string _eotReason = string.Empty;
 
         private readonly object _reconnectTimeLock = new object();
         private DateTime _reconnectTime = DateTime.Now;
@@ -76 +80 @@
         {
         }
 
+        /// <summary>
+        /// Starts the client thread and connects to the server.
+        /// </summary>
         public void Start()
         {
             IsRunning = true;
@@ -83 +90 @@
             _thread.Start();
         }
 
+        /// <summary>
+        /// Gracefully stops the client thread. Blocks until the thread actually stops.
+        /// </summary>
         public void Stop()
         {
             IsRunning = false;
@@ -93 +103 @@
             }
         }
 
-        public string EotMsg
+        /// <summary>
+        /// Contains a reason received in an end-of-transmission message.
+        /// </summary>
+        public string EotReason
         {
-            get => _eotMsg;
-            private set => _eotMsg = value;
+            get => _eotReason;
+            private set => _eotReason = value;
         }
 
+        /// <summary>
+        /// Whether the client is currently maintaining an active connection to the server.
+        /// </summary>
         public bool IsConnected
         {
             get => _isConnected;
             private set => _isConnected = value;
         }
 
+        /// <summary>
+        /// Current position of the actuator (in server's world space).
+        /// </summary>
         public Single3 ActuatorPosition
         {
             get
@@ -123 +142 @@
             } 
         }
 
-        public Single3 CurrentDirectionVector
+        /// <summary>
+        /// The actual direction the actuator is currently moving in.
+        /// </summary>
+        public Single3 ActualDirectionVector
         {
             get
             {
@@ -141 +163 @@
             }
         }
 
-        public Single3 DesiredDirectionVector
+        /// <summary>
+        /// The target direction the actuator should be moving in so that it draws the curve.
+        /// </summary>
+        public Single3 TargetDirectionVector
         {
             get
             {
@@ -159 +184 @@
             }
         }
 
+        /// <summary>
+        /// The current exercise curve.
+        /// </summary>
         public Single3[] Curve
         {
             get
@@ -177 +205 @@
             }
         }
 
+        /// <summary>
+        /// A counter used to determine whether the curve has changed. The curve remains the same while the counter is
+        /// the same.
+        /// </summary>
         public long CurveCounter
         {
             get
@@ -195 +227 @@
             }
         }
 
+        /// <summary>
+        /// Whether the client thread should keep on reading data from the server.
+        /// </summary>
         public bool IsRunning
         {
             get {
@@ -212 +247 @@
             }
         }
 
+        /// <summary>
+        /// The time at which the client will attempt to reconnect to the server again.
+        /// </summary>
         public DateTime ReconnectTime
         {
             get
@@ -230 +268 @@
             }
         }
 
+        /// <summary>
+        /// The client thread function.
+        /// </summary>
         private void ThreadProcedure()
         {
             while (IsRunning)
@@ -294 +335 @@
                     ProcessEot(reader);
                     break;
                 case CurrentActuatorPositionId:
-                    ProcessCurrentActuatorPosition(reader);
+                    ProcessActuatorPosition(reader);
                     break;
                 case CurrentDirectionVectorId:
-                    ProcessCurrentDirectionVector(reader);
+                    ProcessActualDirectionVector(reader);
                     break;
                 case DesiredDirectionVectorId:
-                    ProcessDesiredDirectionVector(reader);
+                    ProcessTargetDirectionVector(reader);
                     break;
                 case CurveId:
                     ProcessCurve(reader);
@@ -373 +414 @@
             reader.ReadBytes((int) numberOfBytes);
         }
 
-        private void ProcessCurrentActuatorPosition(BinaryReader reader)
+        private void ProcessActuatorPosition(BinaryReader reader)
         {
             var x = reader.ReadSingle();
             var y = reader.ReadSingle();
@@ -383 +424 @@
             ActuatorPosition = new Single3(x, y, z);
         }
 
-        private void ProcessCurrentDirectionVector(BinaryReader reader)
+        private void ProcessActualDirectionVector(BinaryReader reader)
         {
             var x = reader.ReadSingle();
             var y = reader.ReadSingle();
             var z = reader.ReadSingle();
             reader.ReadSingle(); // skip unused
 
-            CurrentDirectionVector = new Single3(x, y, z);
+            ActualDirectionVector = new Single3(x, y, z);
         }
 
-        private void ProcessDesiredDirectionVector(BinaryReader reader)
+        private void ProcessTargetDirectionVector(BinaryReader reader)
         {
             var x = reader.ReadSingle();
             var y = reader.ReadSingle();
             var z = reader.ReadSingle();
             reader.ReadSingle(); // skip unused
 
-            DesiredDirectionVector = new Single3(x, y, z);
+            TargetDirectionVector = new Single3(x, y, z);
         }
 
         private void ProcessCurve(BinaryReader reader)
@@ -428 +469 @@
         {
             UInt32 numberOfBytes = reader.ReadUInt32();
             Byte[] buffer = reader.ReadBytes((int) numberOfBytes);
-            EotMsg = Encoding.ASCII.GetString(buffer);
+            EotReason = Encoding.ASCII.GetString(buffer);
             IsConnected = false;
         }
 

deltarobot-vr/Assets/DeltaRobotVr/Components/ActualDirectionArrow.cs

@@ -6 +6 @@
     /// </summary>
     public class ActualDirectionArrow : AbstractArrow
     {
-        protected override Single3 GetVector() => Client.Instance.CurrentDirectionVector;
+        protected override Single3 GetVector() => Client.Instance.ActualDirectionVector;
     }
 }

deltarobot-vr/Assets/DeltaRobotVr/Components/StatusDisplay.cs

@@ -25 +25 @@
         }
         else
         {
-            if (Client.Instance.EotMsg.Length == 0)
+            if (Client.Instance.EotReason.Length == 0)
             {
                 _textComp.text = STATUS + CONNECTING;
             }
             else
             {
-                _textComp.text = STATUS + CONNECTING + "\n" + Client.Instance.EotMsg;
+                _textComp.text = STATUS + CONNECTING + "\n" + Client.Instance.EotReason;
             }
         }
     }

deltarobot-vr/Assets/DeltaRobotVr/Components/TargetDirectionArrow.cs

@@ -6 +6 @@
     /// </summary>
     public class TargetDirectionArrow : AbstractArrow
     {
-        protected override Single3 GetVector() => Client.Instance.DesiredDirectionVector;
+        protected override Single3 GetVector() => Client.Instance.TargetDirectionVector;
     }
 }

deltarobot-vr/Assets/DeltaRobotVr/Single3.cs

@@ -1 +1 @@
 namespace DeltaRobotVr
 {
+    
+    /// <summary>
+    /// A simple 3D float vector.
+    /// </summary>
     public readonly struct Single3
     {
         public float X { get; }

deltarobot-vr/Assets/DeltaRobotVr/Single3Utils.cs

@@ -2 +2 @@
 
 namespace DeltaRobotVr
 {
+    
+    /// <summary>
+    /// Utilities for the <c>Single3</c> struct.
+    /// </summary>
     public class Single3Utils
     {
         public const float PositionScale = 0.001f;