# HG changeset patch
# User IBBoard <dev@ibboard.co.uk>
# Date 1231101816 0
# Node ID 607c3232d6896b795e8de0a53381b768ec45f39e
# Parent  6ad505b6c36e32d7918f86a2b2e3322d03a37c41
Re #11 - Documentation
 * Document Stats and SystemStats at class level to explain the difference
 * Document WarFoundryXmlFactory at class level
Re #13 - XPath for XML loading
 * Load categories using XPath - needs fixing so we can do a proper "categories/cat" query
Re #10 - Refactoring for readability
 * Fix method signature for getting number from attribute added in r19
 * Refactor more code in to GetExtraData method
 * Separate out loading of categories for GameSystem

diff -r 6ad505b6c36e -r 607c3232d689 api/Factories/Xml/WarFoundryXmlFactory.cs
--- a/api/Factories/Xml/WarFoundryXmlFactory.cs	Sun Jan 04 20:06:28 2009 +0000
+++ b/api/Factories/Xml/WarFoundryXmlFactory.cs	Sun Jan 04 20:43:36 2009 +0000
@@ -36,7 +36,7 @@
 namespace IBBoard.WarFoundry.API.Factories.Xml
 {
 	/// <summary>
-	/// Summary description for WarFoundryXmlFactory.
+	/// The WarFoundryXmlFactory loads WarFoundry classes from the native "XML in a zip" file format. Files are validated using the schema for the file type, so structurally invalid files should be identified at initial load.
 	/// </summary>
 	public class WarFoundryXmlFactory : AbstractNativeWarFoundryFactory
 	{
@@ -111,7 +111,7 @@
 				throw new FormatException("Attribute 'maxPoints' of army '"+name+"' was not a valid number");
 			}
 			
-			Army army = new Army(race, name, points, file);//, this);
+			Army army = new Army(race, name, points, file);
 			extraData[army] = elem.OwnerDocument;
 			return army;
 		}
@@ -133,7 +133,6 @@
 			string id = elem.GetAttribute("id");
 			string name = elem.GetAttribute("name");
 			GameSystem system = new GameSystem(id, name, this);
-			//system.SourceZipFile = file.;
 			extraData[system] = elem.OwnerDocument;
 			return system;
 		}
@@ -157,7 +156,6 @@
 			string systemID = elem.GetAttribute("system");
 			string name = elem.GetAttribute("name");
 			Race race = new Race(id, subid, name, systemID, this);
-			//race.SourceZipFile = file; //TODO reference source file
 			extraData[race] = elem.OwnerDocument;
 			return race;
 		}
@@ -176,11 +174,18 @@
 			}
 		}
 	
-		public XmlDocument GetExtraData(IWarFoundryObject obj)
+		public XmlNode GetExtraData(IWarFoundryObject obj)
 		{
 			XmlDocument extra = null;
 			extraData.TryGetValue(obj, out extra);
-			return extra;
+			XmlNode node = null;
+			
+			if (extra !=null)
+			{
+				node = extra.LastChild;
+			}
+			
+			return node;
 		}
 		
 		public void CompleteLoading(GameSystem system)
@@ -191,13 +196,24 @@
 				return;
 			}
 			
-			XmlDocument extra = GetExtraData(system);
-			XmlNode elem = extra.LastChild;
-			
+			XmlNode elem = GetExtraData(system);			
 			XmlNode catsElem = elem.FirstChild;
+			LoadCategoriesForSystem(system, elem);
+						
+			XmlElement statsElem = (XmlElement)catsElem.NextSibling;					
+			LoadSystemStatsFromElement(statsElem, system);
+			string defaultStatsID = statsElem.GetAttribute("defaultStats");
+								
+			LogNotifier.DebugFormat(GetType(), "Completed loading of GameSystem with ID {0}", system.Name);
+			system.StandardSystemStatsID = defaultStatsID;
+			system.SetAsFullyLoaded();
+		}
+		
+		private void LoadCategoriesForSystem(GameSystem system, XmlNode elem)
+		{
 			WarFoundryObject tempObj;
-			
-			foreach (XmlElement cat in catsElem.ChildNodes)
+						
+			foreach (XmlElement cat in elem.SelectNodes("//"+WarFoundryXmlElementName.CATEGORY_ELEMENT.Value))
 			{
 				tempObj = CreateObjectFromElement(cat);
 				
@@ -210,14 +226,6 @@
 					LogNotifier.WarnFormat(GetType(), "Object for string {0} was not of type Category", cat.OuterXml);
 				}
 			}
-						
-			XmlElement statsElem = (XmlElement)catsElem.NextSibling;					
-			LoadSystemStatsFromElement(statsElem, system);
-			string defaultStatsID = statsElem.GetAttribute("defaultStats");
-								
-			LogNotifier.DebugFormat(GetType(), "Completed loading of GameSystem with ID {0}", system.Name);
-			system.StandardSystemStatsID = defaultStatsID;
-			system.SetAsFullyLoaded();
 		}
 		
 		public void CompleteLoading(Race race)
@@ -228,8 +236,7 @@
 				return;
 			}
 			
-			XmlDocument extra = GetExtraData(race);
-			XmlNode elem = extra.LastChild;
+			XmlNode elem = GetExtraData(race);
 			XmlNode colNode = elem.FirstChild;
 			
 			Dictionary<string, UnitType> unitTypes = new Dictionary<string, UnitType>();
@@ -369,7 +376,7 @@
 			return new Category(id, name, minPts, maxPts, minPc, maxPc, minChoices, maxChoices, baseValue, incValue, incAmount);
 		}
 				
-		private GetIntValueFromAttribute(XmlElement elem, string attributeName)
+		private int GetIntValueFromAttribute(XmlElement elem, string attributeName)
 		{
 			try
 			{
diff -r 6ad505b6c36e -r 607c3232d689 api/Objects/Stats.cs
--- a/api/Objects/Stats.cs	Sun Jan 04 20:06:28 2009 +0000
+++ b/api/Objects/Stats.cs	Sun Jan 04 20:43:36 2009 +0000
@@ -24,6 +24,9 @@
 
 namespace IBBoard.WarFoundry.API.Objects
 {
+	/// <summary>
+	/// Stats defines the statistic/attribute values for an entity (for example a unit or any of their equipment that has a stat line) paired against a <see cref=" SystemStats"/> stat line definition.
+	/// </summary>
 	public class Stats
 	{
 		private Stat[] stats;
diff -r 6ad505b6c36e -r 607c3232d689 api/Objects/SystemStats.cs
--- a/api/Objects/SystemStats.cs	Sun Jan 04 20:06:28 2009 +0000
+++ b/api/Objects/SystemStats.cs	Sun Jan 04 20:43:36 2009 +0000
@@ -4,7 +4,7 @@
 namespace IBBoard.WarFoundry.API.Objects
 {
 	/// <summary>
-	/// Summary description for SystemStats.
+	/// SystemStats defines the available statistics/attributes that entity types can use (either a unit or an equipment item that has a stats line). Statistic/attribute values will be defined by a <see cref="Stats"/> object.
 	/// </summary>
 	public class SystemStats
 	{