# HG changeset patch
# User IBBoard <dev@ibboard.co.uk>
# Date 1237061647 0
# Node ID d7899f462d8cc8bb7cbf221a66e566367625d66f
# Parent  e5ea6bfcde8333f1fdcd8671e619a3570420b787
Re #11 - Document methods
 * Document FileLoadFailure and rationalise constructors
Also added parameter for holding the Exception that caused the failure

diff -r e5ea6bfcde83 -r d7899f462d8c api/FileLoadFailure.cs
--- a/api/FileLoadFailure.cs	Sat Mar 14 19:18:43 2009 +0000
+++ b/api/FileLoadFailure.cs	Sat Mar 14 20:14:07 2009 +0000
@@ -9,6 +9,9 @@
 
 namespace IBBoard.WarFoundry.API
 {
+	/// <summary>
+	/// A container class that holds information about file load failures. Core information covers the file that failed and a message. Additional information includes the factory loading the file and the excetion that was thrown. Messages are passed through <code>String.Format</code> and supplied with the failed file path and the failing factory
+	/// </summary>
 	public class FileLoadFailure
 	{
 		private FileInfo failedFile;
@@ -16,25 +19,68 @@
 		private string defaultMessage;
 		private string messageTranslationID;
 		private string message;
-
-		public FileLoadFailure(FileInfo file, string message) : this (file, message, "")
+		private Exception cause;
+		
+		/// <summary>
+		/// Constructor for a failed file load where no factory was found. Translatable messages can be providied through a <code>translationID</code> or skipped by passing <code>null</code>.
+		/// </summary>
+		/// <param name="file">
+		/// The <see cref="FileInfo"/> that failed to load
+		/// </param>
+		/// <param name="message">
+		/// A message about the failure in English - used as a default fall-back message.
+		/// </param>
+		/// <param name="translationID">
+		/// The ID of a translation for the message.
+		/// </param>
+		public FileLoadFailure(FileInfo file, string message, string translationID) : this (file, null, message, "")
 		{
 		}
 		
-		public FileLoadFailure(FileInfo file, string message, string translationID) : this (file, null, message, "")
-		{
-		}
-
-		public FileLoadFailure(FileInfo file, IWarFoundryFactory factory, string message) : this (file, factory, message, "")
+		/// <summary>
+		/// Constructor for a failed file load where a factory was identified as supporting the file but failed to load it. Translatable messages can be providied through a <code>translationID</code> or skipped by passing <code>null</code>.
+		/// </summary>
+		/// <param name="file">
+		/// The <see cref="FileInfo"/> that failed to load
+		/// </param>
+		/// <param name="factory">
+		/// The <see cref="IWarFoundryFactory"/> that failed to load the file
+		/// </param>
+		/// <param name="message">
+		/// A message about the failure in English - used as a default fall-back message.
+		/// </param>
+		/// <param name="translationID">
+		/// The ID of a translation for the message.
+		/// </param>
+		public FileLoadFailure(FileInfo file, IWarFoundryFactory factory, string message, string translationID) : this(file, factory, message, translationID, null)
 		{
 		}
 		
-		public FileLoadFailure(FileInfo file,IWarFoundryFactory factory, string message, string translationID)
+		/// <summary>
+		/// Constructor for a failed file load where a factory was identified as supporting the file but an exception occurred while loading it. Translatable messages can be providied through a <code>translationID</code> or skipped by passing <code>null</code>.
+		/// </summary>
+		/// <param name="file">
+		/// The <see cref="FileInfo"/> that failed to load
+		/// </param>
+		/// <param name="factory">
+		/// The <see cref="IWarFoundryFactory"/> that failed to load the file
+		/// </param>
+		/// <param name="message">
+		/// A message about the failure in English - used as a default fall-back message.
+		/// </param>
+		/// <param name="translationID">
+		/// The ID of a translation for the message.
+		/// </param>
+		/// <param name="exception">
+		/// The <see cref="Exception"/> that occurred to cause the load to fail
+		/// </param>
+		public FileLoadFailure(FileInfo file, IWarFoundryFactory factory, string message, string translationID, Exception exception)
 		{
 			failedFile = file;
 			loadingFactory = factory;
 			defaultMessage = message;
 			messageTranslationID = translationID;
+			cause = exception;
 		}
 
 		public FileInfo FailedFile
@@ -51,18 +97,25 @@
 			{
 				if (message == null)
 				{
-					if (messageTranslationID == "")
+					string fileName = FailedFile.FullName;
+					string factoryType = (loadingFactory == null ? "" : loadingFactory.GetType().Name);
+					if (messageTranslationID == "" || messageTranslationID == null)
 					{
-						message = String.Format(defaultMessage, FailedFile, loadingFactory);
+						message = String.Format(defaultMessage, fileName, factoryType);
 				 	}
 					else
 				 	{
-						message = Translation.GetTranslation(messageTranslationID, defaultMessage, failedFile, loadingFactory);
+						message = Translation.GetTranslation(messageTranslationID, defaultMessage, fileName, factoryType);
 					}
 				}
 				
 				return message;
 			}
 		}
+		
+		public Exception Exception
+		{
+			get { return cause; }
+		}
 	}
 }