changeset 46:a5855fcd75ab

Re #11 - Document classes and methods * Document methods in UnitType and Category classes
author IBBoard <dev@ibboard.co.uk>
date Mon, 23 Mar 2009 20:57:07 +0000
parents 75a44b7753d4
children 85f2b9c3609c
files api/Objects/Category.cs api/Objects/UnitType.cs
diffstat 2 files changed, 98 insertions(+), 28 deletions(-) [+]
line diff
     1.1 --- a/api/Objects/Category.cs	Mon Mar 23 20:21:41 2009 +0000
     1.2 +++ b/api/Objects/Category.cs	Mon Mar 23 20:57:07 2009 +0000
     1.3 @@ -9,7 +9,7 @@
     1.4  namespace IBBoard.WarFoundry.API.Objects
     1.5  {
     1.6  	/// <summary>
     1.7 -	/// Summary description for Category.
     1.8 +	/// A Category is a definition at the <see cref=" GameSystem"/> or <see cref=" Race"/> level of a group that <see cref=" UnitType"/>s belong to. Each category has a name and a min/max limit on points or percentage of a total army cost that units in the category can total.
     1.9  	/// </summary>
    1.10  	public class Category : WarFoundryObject
    1.11  	{
    1.12 @@ -35,8 +35,11 @@
    1.13  		protected override string DefaultName()
    1.14  		{
    1.15  			return "";
    1.16 -		}
    1.17 -
    1.18 +		}
    1.19 +		
    1.20 +		/// <value>
    1.21 +		/// Gets or sets the minimum number of points that the units of this category can cost. Note: This should be set AFTER MaximumPoints, otherwise an unintended default value may be set for the minimum
    1.22 +		/// </value>
    1.23  		public int MinimumPoints
    1.24  		{
    1.25  			get { return minPts; }
    1.26 @@ -46,7 +49,10 @@
    1.27  				CheckMinimumPoints();
    1.28  			}
    1.29  		}
    1.30 -
    1.31 +		
    1.32 +		/// <value>
    1.33 +		/// Gets or sets the maximum number of points that the units of this category can cost. Note: This should be set BEFORE MinimumPoints, otherwise an unintended default value may be set for the minimum
    1.34 +		/// </value>
    1.35  		public int MaximumPoints
    1.36  		{
    1.37  			get { return maxPts; }
    1.38 @@ -55,8 +61,11 @@
    1.39  				maxPts = (value >= 0 ? value : WarFoundryCore.INFINITY);
    1.40  				CheckMinimumPoints();
    1.41  			}
    1.42 -		}
    1.43 -
    1.44 +		}
    1.45 +		
    1.46 +		/// <summary>
    1.47 +		/// Makes sure that the minimum points value isn't more than the maximum points value, hence the warning on the properties
    1.48 +		/// </summary>
    1.49  		private void CheckMinimumPoints()
    1.50  		{
    1.51  			if (MinimumPoints > MaximumPoints && MaximumPoints!=WarFoundryCore.INFINITY)
    1.52 @@ -66,6 +75,9 @@
    1.53  			}
    1.54  		}
    1.55  		
    1.56 +		/// <value>
    1.57 +		/// Gets or sets the minimum percentage of the total army points value that the units of this category can cost. Note: This should be set AFTER MaximumPercentage, otherwise an unintended default value may be set for the minimum
    1.58 +		/// </value>
    1.59  		public int MinimumPercentage
    1.60  		{
    1.61  			get { return minPc; }
    1.62 @@ -74,8 +86,11 @@
    1.63  				minPc = (value >= 0 ? value : 0);
    1.64  				CheckMinimumPercentage();
    1.65  			}
    1.66 -		}
    1.67 -
    1.68 +		}
    1.69 +		
    1.70 +		/// <value>
    1.71 +		/// Gets or sets the maximum percentage of the total army points value that the units of this category can cost. Note: This should be set BEFORE MinimumPercentage, otherwise an unintended default value may be set for the minimum
    1.72 +		/// </value>
    1.73  		public int MaximumPercentage
    1.74  		{
    1.75  			get { return maxPc; }
    1.76 @@ -96,8 +111,11 @@
    1.77  				
    1.78  				CheckMinimumPercentage();
    1.79  			}
    1.80 -		}
    1.81 -
    1.82 +		}
    1.83 +		
    1.84 +		/// <summary>
    1.85 +		/// Makes sure that the minimum percentage value isn't more than the maximum points value, hence the warning on the properties
    1.86 +		/// </summary>
    1.87  		private void CheckMinimumPercentage()
    1.88  		{
    1.89  			if (MinimumPercentage > MaximumPercentage)
     2.1 --- a/api/Objects/UnitType.cs	Mon Mar 23 20:21:41 2009 +0000
     2.2 +++ b/api/Objects/UnitType.cs	Mon Mar 23 20:57:07 2009 +0000
     2.3 @@ -12,7 +12,7 @@
     2.4  namespace IBBoard.WarFoundry.API.Objects
     2.5  {
     2.6  	/// <summary>
     2.7 -	/// Summary description for Unit.
     2.8 +	/// A UnitType is a type for a <see cref=" Unit"/>, normally relating to an entry in an army list. The UnitType defines the name, cost, minimum and maximum limits of a unit, and the equipment units of the type can take.
     2.9  	/// </summary>
    2.10  	public class UnitType : WarFoundryObject
    2.11  	{
    2.12 @@ -52,12 +52,18 @@
    2.13  				AddRequirement(requirement);
    2.14  			}
    2.15  		}
    2.16 -
    2.17 +
    2.18 +		/// <value>
    2.19 +		/// Gets the <see cref=" Race"/> that this unit belongs to.
    2.20 +		/// </value>
    2.21  		public Race Race
    2.22  		{
    2.23  			get { return race; }
    2.24  		}
    2.25 -
    2.26 +
    2.27 +		/// <value>
    2.28 +		/// Gets or sets the <see cref=" Category"/> that this unit type is a member of.
    2.29 +		/// </value>
    2.30  		public virtual Category MainCategory
    2.31  		{
    2.32  			get
    2.33 @@ -69,7 +75,10 @@
    2.34  				mainCat = value;
    2.35  			}
    2.36  		}
    2.37 -
    2.38 +
    2.39 +		/// <value>
    2.40 +		/// Gets or sets the minimum size of each unit of this type. Note: This should be set AFTER MaxSize, otherwise an unintended default value may be set for the minimum
    2.41 +		/// </value>
    2.42  		public int MinSize
    2.43  		{
    2.44  			get { return minSize; }
    2.45 @@ -79,7 +88,10 @@
    2.46  				CheckMinimumSize();
    2.47  			}
    2.48  		}
    2.49 -
    2.50 +
    2.51 +		/// <value>
    2.52 +		/// Gets or sets the maximum size of each unit of this type. Note: This should be set BEFORE MinSize, otherwise an unintended default value may be set for the minimum
    2.53 +		/// </value>
    2.54  		public int MaxSize
    2.55  		{
    2.56  			get { return maxSize; }
    2.57 @@ -89,12 +101,10 @@
    2.58  				CheckMinimumSize();
    2.59  			}
    2.60  		}
    2.61 -		
    2.62 -		public int BaseSize
    2.63 -		{
    2.64 -			get { return baseSize; }
    2.65 -		}
    2.66 -
    2.67 +		
    2.68 +		/// <value>
    2.69 +		/// Gets or sets the minimum number of units of this type that must be taken in an army. Note: This should be set AFTER MaxNumber, otherwise an unintended default value may be set for the minimum
    2.70 +		/// </value>
    2.71  		public int MinNumber
    2.72  		{
    2.73  			get { return min; }
    2.74 @@ -104,7 +114,10 @@
    2.75  				CheckMinimumNumber();
    2.76  			}
    2.77  		}
    2.78 -
    2.79 +
    2.80 +		/// <value>
    2.81 +		/// Gets or sets the maximum number of units of this type that can be taken in an army. Note: This should be set BEFORE MinNumber, otherwise an unintended default value may be set for the minimum
    2.82 +		/// </value>
    2.83  		public int MaxNumber
    2.84  		{
    2.85  			get { return max; }
    2.86 @@ -114,7 +127,10 @@
    2.87  				CheckMinimumNumber();
    2.88  			}
    2.89  		}
    2.90 -
    2.91 +
    2.92 +		/// <summary>
    2.93 +		/// Makes sure that the minimum number isn't more than the maximum number, hence the warning on the properties
    2.94 +		/// </summary>
    2.95  		private void CheckMinimumNumber()
    2.96  		{
    2.97  			if (MinNumber > MaxNumber && MaxNumber!=WarFoundryCore.INFINITY)
    2.98 @@ -123,7 +139,10 @@
    2.99  				LogNotifier.WarnFormat(GetType(), "Unit type {0} ({1}) had a minimum number greater than their maximum number.", Name, ID);
   2.100  			}
   2.101  		}
   2.102 -
   2.103 +
   2.104 +		/// <summary>
   2.105 +		/// Makes sure that the minimum unit size isn't more than the maximum unit size, hence the warning on the properties
   2.106 +		/// </summary>
   2.107  		private void CheckMinimumSize()
   2.108  		{
   2.109  			if (MinSize > MaxSize && MaxSize!=WarFoundryCore.INFINITY)
   2.110 @@ -133,12 +152,27 @@
   2.111  			}
   2.112  		}
   2.113  		
   2.114 +		//// <value>
   2.115 +		/// Gets or sets the "base size" of a unit, which is the number of troopers the unit has in it for its "base cost". For a lot of units this value will be 0 as the cost is worked out based on the total number of members.
   2.116 +		/// </value>
   2.117 +		public int BaseSize
   2.118 +		{
   2.119 +			get { return baseSize; }
   2.120 +			set { baseSize = (value >= 0 ? value : 0); }
   2.121 +		}
   2.122 +		
   2.123 +		/// <value>
   2.124 +		/// The number of points that a "base unit" of <code>BaseSize</code> models costs. Additional models are charged at <code>CostPerTrooper</code> each.
   2.125 +		/// </value>
   2.126  		public double BaseUnitCost
   2.127  		{
   2.128  			get { return baseUnitCost; }
   2.129  			set { baseUnitCost = (value >= 0 ? value : 0); }
   2.130  		}
   2.131 -
   2.132 +
   2.133 +		//// <value>
   2.134 +		/// The cost of an individual trooper. This value is the cost for a basic trooper without weapons, which are added on top of the cost before calculating a unit cost.
   2.135 +		/// </value>
   2.136  		public double CostPerTrooper
   2.137  		{
   2.138  			get { return costPerTrooper; }
   2.139 @@ -149,7 +183,10 @@
   2.140  		{
   2.141  			throw new InvalidOperationException("Unit type with id "+id+" did not have a name specified");
   2.142  		}
   2.143 -
   2.144 +
   2.145 +		/// <value>
   2.146 +		/// The <see cref=" Stats"/> for the unit in a format that is valid for the game system.
   2.147 +		/// </value>
   2.148  		public Stats UnitStats
   2.149  		{
   2.150  			get 
   2.151 @@ -164,12 +201,27 @@
   2.152  				}
   2.153  			}
   2.154  		}
   2.155 -
   2.156 +
   2.157 +		/// <summary>
   2.158 +		/// Gets a <see cref="UnitEquipmentItem"/> for the given ID string, or <code>null</code> if nothing exists for that ID
   2.159 +		/// </summary>
   2.160 +		/// <param name="id">
   2.161 +		/// The ID of the UnitEquipmentItem to get
   2.162 +		/// </param>
   2.163 +		/// <returns>
   2.164 +		/// The <see cref="UnitEquipmentItem"/> for the given ID string, or <code>null</code> if nothing exists for that ID
   2.165 +		/// </returns>
   2.166  		public UnitEquipmentItem GetEquipmentItem(string id)
   2.167  		{
   2.168  			return (UnitEquipmentItem)equipment[id];
   2.169  		}
   2.170 -
   2.171 +
   2.172 +		/// <summary>
   2.173 +		/// Gets an array of all available <see cref="UnitEquipmentItem"/>s for this UnitType
   2.174 +		/// </summary>
   2.175 +		/// <returns>
   2.176 +		/// An array of all available <see cref="UnitEquipmentItem"/>s for this UnitType
   2.177 +		/// </returns>
   2.178  		public UnitEquipmentItem[] GetEquipmentItems()
   2.179  		{
   2.180  			UnitEquipmentItem[] items = new UnitEquipmentItem[equipment.Count];