Mercurial > repos > snowblizz-super-API-ideas

changeset 46:a5855fcd75ab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 wrap: on
line diff
--- a/api/Objects/Category.cs	Mon Mar 23 20:21:41 2009 +0000
+++ b/api/Objects/Category.cs	Mon Mar 23 20:57:07 2009 +0000
@@ -9,7 +9,7 @@
 namespace IBBoard.WarFoundry.API.Objects
 {
 	/// <summary>
-	/// Summary description for Category.
+	/// 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.
 	/// </summary>
 	public class Category : WarFoundryObject
 	{
@@ -35,8 +35,11 @@
 		protected override string DefaultName()
 		{
 			return "";
-		}
-
+		}
+		
+		/// <value>
+		/// 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
+		/// </value>
 		public int MinimumPoints
 		{
 			get { return minPts; }
@@ -46,7 +49,10 @@
 				CheckMinimumPoints();
 			}
 		}
-
+		
+		/// <value>
+		/// 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
+		/// </value>
 		public int MaximumPoints
 		{
 			get { return maxPts; }
@@ -55,8 +61,11 @@
 				maxPts = (value >= 0 ? value : WarFoundryCore.INFINITY);
 				CheckMinimumPoints();
 			}
-		}
-
+		}
+		
+		/// <summary>
+		/// Makes sure that the minimum points value isn't more than the maximum points value, hence the warning on the properties
+		/// </summary>
 		private void CheckMinimumPoints()
 		{
 			if (MinimumPoints > MaximumPoints && MaximumPoints!=WarFoundryCore.INFINITY)
@@ -66,6 +75,9 @@
 			}
 		}
 		
+		/// <value>
+		/// 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
+		/// </value>
 		public int MinimumPercentage
 		{
 			get { return minPc; }
@@ -74,8 +86,11 @@
 				minPc = (value >= 0 ? value : 0);
 				CheckMinimumPercentage();
 			}
-		}
-
+		}
+		
+		/// <value>
+		/// 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
+		/// </value>
 		public int MaximumPercentage
 		{
 			get { return maxPc; }
@@ -96,8 +111,11 @@
 				
 				CheckMinimumPercentage();
 			}
-		}
-
+		}
+		
+		/// <summary>
+		/// Makes sure that the minimum percentage value isn't more than the maximum points value, hence the warning on the properties
+		/// </summary>
 		private void CheckMinimumPercentage()
 		{
 			if (MinimumPercentage > MaximumPercentage)
--- a/api/Objects/UnitType.cs	Mon Mar 23 20:21:41 2009 +0000
+++ b/api/Objects/UnitType.cs	Mon Mar 23 20:57:07 2009 +0000
@@ -12,7 +12,7 @@
 namespace IBBoard.WarFoundry.API.Objects
 {
 	/// <summary>
-	/// Summary description for Unit.
+	/// 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.
 	/// </summary>
 	public class UnitType : WarFoundryObject
 	{
@@ -52,12 +52,18 @@
 				AddRequirement(requirement);
 			}
 		}
-
+
+		/// <value>
+		/// Gets the <see cref=" Race"/> that this unit belongs to.
+		/// </value>
 		public Race Race
 		{
 			get { return race; }
 		}
-
+
+		/// <value>
+		/// Gets or sets the <see cref=" Category"/> that this unit type is a member of.
+		/// </value>
 		public virtual Category MainCategory
 		{
 			get
@@ -69,7 +75,10 @@
 				mainCat = value;
 			}
 		}
-
+
+		/// <value>
+		/// 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
+		/// </value>
 		public int MinSize
 		{
 			get { return minSize; }
@@ -79,7 +88,10 @@
 				CheckMinimumSize();
 			}
 		}
-
+
+		/// <value>
+		/// 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
+		/// </value>
 		public int MaxSize
 		{
 			get { return maxSize; }
@@ -89,12 +101,10 @@
 				CheckMinimumSize();
 			}
 		}
-		
-		public int BaseSize
-		{
-			get { return baseSize; }
-		}
-
+		
+		/// <value>
+		/// 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
+		/// </value>
 		public int MinNumber
 		{
 			get { return min; }
@@ -104,7 +114,10 @@
 				CheckMinimumNumber();
 			}
 		}
-
+
+		/// <value>
+		/// 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
+		/// </value>
 		public int MaxNumber
 		{
 			get { return max; }
@@ -114,7 +127,10 @@
 				CheckMinimumNumber();
 			}
 		}
-
+
+		/// <summary>
+		/// Makes sure that the minimum number isn't more than the maximum number, hence the warning on the properties
+		/// </summary>
 		private void CheckMinimumNumber()
 		{
 			if (MinNumber > MaxNumber && MaxNumber!=WarFoundryCore.INFINITY)
@@ -123,7 +139,10 @@
 				LogNotifier.WarnFormat(GetType(), "Unit type {0} ({1}) had a minimum number greater than their maximum number.", Name, ID);
 			}
 		}
-
+
+		/// <summary>
+		/// Makes sure that the minimum unit size isn't more than the maximum unit size, hence the warning on the properties
+		/// </summary>
 		private void CheckMinimumSize()
 		{
 			if (MinSize > MaxSize && MaxSize!=WarFoundryCore.INFINITY)
@@ -133,12 +152,27 @@
 			}
 		}
 		
+		//// <value>
+		/// 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.
+		/// </value>
+		public int BaseSize
+		{
+			get { return baseSize; }
+			set { baseSize = (value >= 0 ? value : 0); }
+		}
+		
+		/// <value>
+		/// The number of points that a "base unit" of <code>BaseSize</code> models costs. Additional models are charged at <code>CostPerTrooper</code> each.
+		/// </value>
 		public double BaseUnitCost
 		{
 			get { return baseUnitCost; }
 			set { baseUnitCost = (value >= 0 ? value : 0); }
 		}
-
+
+		//// <value>
+		/// 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.
+		/// </value>
 		public double CostPerTrooper
 		{
 			get { return costPerTrooper; }
@@ -149,7 +183,10 @@
 		{
 			throw new InvalidOperationException("Unit type with id "+id+" did not have a name specified");
 		}
-
+
+		/// <value>
+		/// The <see cref=" Stats"/> for the unit in a format that is valid for the game system.
+		/// </value>
 		public Stats UnitStats
 		{
 			get 
@@ -164,12 +201,27 @@
 				}
 			}
 		}
-
+
+		/// <summary>
+		/// Gets a <see cref="UnitEquipmentItem"/> for the given ID string, or <code>null</code> if nothing exists for that ID
+		/// </summary>
+		/// <param name="id">
+		/// The ID of the UnitEquipmentItem to get
+		/// </param>
+		/// <returns>
+		/// The <see cref="UnitEquipmentItem"/> for the given ID string, or <code>null</code> if nothing exists for that ID
+		/// </returns>
 		public UnitEquipmentItem GetEquipmentItem(string id)
 		{
 			return (UnitEquipmentItem)equipment[id];
 		}
-
+
+		/// <summary>
+		/// Gets an array of all available <see cref="UnitEquipmentItem"/>s for this UnitType
+		/// </summary>
+		/// <returns>
+		/// An array of all available <see cref="UnitEquipmentItem"/>s for this UnitType
+		/// </returns>
 		public UnitEquipmentItem[] GetEquipmentItems()
 		{
 			UnitEquipmentItem[] items = new UnitEquipmentItem[equipment.Count];