Commented research model

Space4x/Assets/Scripts/Research/Model/ResearchModel.cs

@@ -1,14 +1,28 @@
+/**
+ * @file 
+ * 
+ * @author Marc de Craigher
+ * @author Aaron Moser
+ * 
+ * @package Assets.Scripts.Research.Model
+ */
 using System.Collections;
 using System.Collections.Generic;
 using UnityEngine;
 
+/**
+ * @section DESCRIPTION
+ * 
+ * Class contains research model.
+ */
 public class ResearchModel
 {
-    private ResearchQueueModel _researchQueueModel;
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Public values
 
-    /// <summary>
-    /// 
-    /// </summary>
+    /**
+     * Property references research queue model.
+     */
     public ResearchQueueModel ResearchQueueModel
     {
         get
@@ -25,11 +39,9 @@ public class ResearchModel
         }
     }
 
-    private NTechnology.Technologies _techs;
-
-    /// <summary>
-    /// 
-    /// </summary>
+    /**
+     * Property references technologies of a player.
+     */
     public NTechnology.Technologies Techs
     {
         get
@@ -46,8 +58,28 @@ public class ResearchModel
         }
     }
 
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Private values
+
+    /**
+     * Private reference to research queue model, administrated by property.
+     */
+    private ResearchQueueModel _researchQueueModel;
+
+    /**
+     * Private reference to technologies of player, administrated by property.
+     */
+    private NTechnology.Technologies _techs;
+
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Public functions
+
+    /**
+     * Constructor doesn't initialize any values.
+     */
     public ResearchModel()
-    {
-        
-    }
+    {}
+
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Private functions
 }

Space4x/Assets/Scripts/Research/Model/ResearchQueueModel.cs

@@ -1,44 +1,27 @@
 /**
- * @file Manages the science queue.
- * @author Marc
+ * @file 
+ * 
+ * @author Marc de Craigher
+ * @author Aaron Moser
+ * 
+ * @package Assets.Scripts.Research.Model
  */
 using System;
 using System.Threading;
 
+/**
+ * @section DESCRIPTION
+ * 
+ * Class contains research queue model.
+ */
 public class ResearchQueueModel
 {
-    private const int TECHQUEUESIZE = 4;
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Public values
 
-    private int iTechQueuePointer;
-
-    private string[] TechnologyQueue;
-
-    private ReaderWriterLockSlim _rwTechQueueLock;
-
-    private object _techQueuePointerLock;
-
-    /// <summary>
-    /// Constructor initializes TechQueuePointer and TechnologyQueue.
-    /// </summary>
-    public ResearchQueueModel()
-    {
-        iTechQueuePointer = 0;
-        TechnologyQueue = new string[TECHQUEUESIZE];
-        _rwTechQueueLock = new ReaderWriterLockSlim();
-        _techQueuePointerLock = new object();
-    }
-
-    /// <summary>
-    /// Deconstructor disposes rwLock at destruction of this object.
-    /// </summary>
-    ~ResearchQueueModel()
-    {
-        _rwTechQueueLock.Dispose();
-    }
-
-    /// <summary>
-    /// Enum representing the different return possibilities.
-    /// </summary>
+    /**
+     * Enum representing the different return possibilities.
+     */
     public enum EScienceQueueManagerReturnCodes
     {
         TechnologyAddedToQueue,
@@ -48,11 +31,69 @@ public class ResearchQueueModel
         Error
     }
 
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Private values
+
     /**
-     * Returns the elment at given index, if index is valid.
-     * @param iIndex
-     * IndexOutOfRangeException
-     * @return string
+     * Maximum size of tech queue.
+     */
+    private const int TECHQUEUESIZE = 4;
+
+    /**
+     * Tech queue pointer, points behind last element of tech queue.
+     */
+    private int iTechQueuePointer;
+
+    /**
+     * Reference to research tech queue.
+     */
+    private string[] TechnologyQueue;
+
+    /**
+     * Reader writer loch to synchronize access to research tech queue.
+     */
+    private ReaderWriterLockSlim _rwTechQueueLock;
+
+    /**
+     * Object which monitor is used to synchronize access to research tech queue pointer.
+     */
+    private object _techQueuePointerLock;
+
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Constructors / Destructors
+
+    /**
+     * Constructor initializes TechQueuePointer and TechnologyQueue.
+     * Also initializes reader writer lock, to synchronize access to tech queue.
+     * And object to lock access to tech queue pointer via it's monitor.
+     */
+    public ResearchQueueModel()
+    {
+        iTechQueuePointer = 0;
+        TechnologyQueue = new string[TECHQUEUESIZE];
+        _rwTechQueueLock = new ReaderWriterLockSlim();
+        _techQueuePointerLock = new object();
+    }
+
+    /**
+     * Deconstructor disposes rwLock at destruction of this object.
+     */
+    ~ResearchQueueModel()
+    {
+        _rwTechQueueLock.Dispose();
+    }
+
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Public functions
+
+    /**
+     * Returns the element at given index, if index is valid.
+     * 
+     * @param iIndex, index of element at queue to get.
+     * 
+     * @throws IndexOutOfRangeException, if iIndex is out of range.
+     * 
+     * @return string indicating the element at queue index.
      */
     public string GetTechnologyQueueElement(int iIndex)
     {
@@ -75,12 +116,15 @@ public class ResearchQueueModel
         return sTechnology;
     }
 
-    /// <summary>
-    /// Adds technology indicated by overhanded enum value to queue, if the queue is not full.
-    /// </summary>
-    /// <param name="Tech"></param>
-    /// <returns></returns>
-    /// <exception cref="Exception"></exception>
+    /**
+     * Adds technology indicated by overhanded enum value to queue, if the queue is not full.
+     * 
+     * @param Tech, technology to add to queue.
+     * 
+     * @throws Exception if tech queue pointer has invalid value.
+     * 
+     * @return Error if something went wrong, TechnologyAddedToQueue if technology was added to queue or QueueFull if queue is full.
+     */
     public EScienceQueueManagerReturnCodes AddTechnologyQueueElement(NTechnology.ETechnology Tech)
     {
         bool TechQueuePointerExceptionOccurred = false;
@@ -122,11 +166,12 @@ public class ResearchQueueModel
         return eReturnCode;
     }
 
-    /// <summary>
-    /// Pops first element of queue and moves all elements one to the left.
-    /// Replaces the last with null.
-    /// </summary>
-    /// <returns>String representing the popped first element. "--" if queue is empty.</returns>
+    /**
+     * Pops first element of queue and moves all elements one to the left.
+     * Replaces the last with null.
+     * 
+     * @return String representing the popped first element. "--" if queue is empty.
+     */
     public string PopFirstTechnologyQueueElement()
     {
         string sPoppedElement = "--";
@@ -154,10 +199,11 @@ public class ResearchQueueModel
         return sPoppedElement;
     }
 
-    /// <summary>
-    /// Removes last technology element from queue if queue is not empty.
-    /// </summary>
-    /// <returns></returns>
+    /**
+     * Removes last technology element from queue if queue is not empty.
+     * 
+     * @returns Error if something went wrong, TechnologyRemovedFromQueue if technology was removed from queue or QueueEmpty if queue is empty.
+     */
     public EScienceQueueManagerReturnCodes RemoveLastTechnologyQueueElement()
     {
         EScienceQueueManagerReturnCodes eReturnCode = EScienceQueueManagerReturnCodes.Error;
@@ -184,4 +230,7 @@ public class ResearchQueueModel
 
         return eReturnCode;
     }
+
+    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    // Private functions
 }