SpriteDatabase better documentation of XML Write functions

SpriteLibrary/SpriteDatabase.cs

@@ -23,8 +23,70 @@ namespace SpriteLibrary
     /// Store Sprite information in a database.  You can preload your database with sprite definitions, and then
     /// create the sprites as needed.  This can drastically reduce the initial load time of a game or something.
     /// Though, what it really does is spread out the load time.  It still takes the same amount of time to
-    /// load all the sprites, it just loads them on-demand.  Using a dictionary often hides any load time issues.
+    /// load all the sprites, it just loads them on-demand.  Using a SpriteDatabase often hides any load time issues.
     /// </summary>
+    /// <example>
+    /// This is an example of how to use a SpriteDatabase.
+    /// When you begin developing your project, you want to start by creating a SpriteDatabase and pointing
+    /// it to a file, and then opening up an <see cref="SpriteDatabase.OpenEditWindow(int)">EditorWindow.</see>
+    /// <code lang="C#">
+    /// public partial class MyGameForm : Form
+    /// {
+    ///     SpriteController mySpriteController = null;
+    ///     SpriteDatabase mySpriteDatabase = null;
+    ///     
+    ///     public MyGameForm()
+    ///     {
+    ///         InitializeComponent();
+    ///         MainDrawingArea.BackgroundImage = Properties.Resources.Background;
+    ///         MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
+    ///         
+    ///         string Desktop = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);
+    ///         string MyFile = Path.Combine(Desktop, "myFile.xml");
+    ///         mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, MyFile);
+    ///         
+    ///         mySpriteController = new SpriteController(MainDrawingArea, mySpriteDatabase);
+    ///         
+    ///         mySpriteDatabase.OpenEditWindow();
+    ///         mySpriteDatabase.Save();
+    ///     }
+    /// }
+    /// </code>
+    /// The Editor Window will let you find the sprites that are contained in the various images you have
+    /// as resources in your program, and it will save a file with those sprite templates.  Any SpriteController
+    /// that you have instantiated with a Sprite Database (see <see cref="SpriteController(PictureBox, SpriteDatabase)"/>)
+    /// will now be able to create named sprites from the templates defined in the database.  After the first use, the
+    /// named sprites will be accessible from within that controller just like any other named sprites.
+    /// <para/>
+    /// After you have created your SpriteDatabase file, you will want to add your file to your program resources.
+    /// Then, you will change the SpriteDatabase to use the resource instead of a file.  If we named the file
+    /// "MySpriteDatabase.xml", and it got added to your resources with the name "MySpriteDatabase", you would
+    /// pass "MySpriteDatabase" to the database instantiation.
+    /// <code lang="C#">
+    /// public partial class MyGameForm : Form
+    /// {
+    ///     SpriteController mySpriteController = null;
+    ///     SpriteDatabase mySpriteDatabase = null;
+    ///     
+    ///     public MyGameForm()
+    ///     {
+    ///         InitializeComponent();
+    ///         MainDrawingArea.BackgroundImage = Properties.Resources.Background;
+    ///         MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
+    ///         
+    ///         //string Desktop = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);
+    ///         //string MyFile = Path.Combine(Desktop, "myFile.xml");
+    ///         //mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, MyFile);
+    ///         mySpriteDatabase = new SpriteDatabase(Properties.Resources.ResourceManager, "MySpriteDatabase");
+    ///         
+    ///         mySpriteController = new SpriteController(MainDrawingArea, mySpriteDatabase);
+    ///         
+    ///         //mySpriteDatabase.OpenEditWindow();
+    ///         //mySpriteDatabase.Save();
+    ///     }
+    /// }
+    /// </code>
+    /// </example>
     public class SpriteDatabase
     {
         /// <summary>
@@ -193,7 +255,7 @@ namespace SpriteLibrary
         /// that you have instantiated with a Sprite Database (see <see cref="SpriteController(PictureBox, SpriteDatabase)"/>)
         /// will now be able to create named sprites from the templates defined in the database.  After the first use, the
         /// named sprites will be accessible from within that controller just like any other named sprites.
-        /// 
+        /// <para/>
         /// After you have created your SpriteDatabase file, you will want to add your file to your program resources.
         /// Then, you will change the SpriteDatabase to use the resource instead of a file.  If we named the file
         /// "MySpriteDatabase.xml", and it got added to your resources with the name "MySpriteDatabase", you would
@@ -341,11 +403,32 @@ namespace SpriteLibrary
         #region Generic XML Funcs
 
         /// <summary>
-        /// Load in an XML serialized item from the specified ResourceManager.  You will usually make one of these by
+        /// Load in an XML serialized item from the specified ResourceManager.  You will usually make an XML file by
-        /// creating an object and using <see cref="WriteToXmlFile{T}(string, T)"/> SpriteDatabase.WriteToXmlFile to
+        /// creating an object (as a variable) and using <see cref="WriteToXmlFile{T}(string, T)"/> to
-        /// save it to a file on your desktop.  Then you can drag and drop that file into your project and then use this 
+        /// serialize it and save it to a file on your desktop.  Then you can drag and drop that file into your project and then use this 
-        /// LoadObjectFromXmlFile function.
+        /// LoadObjectFromXmlFile function.  You can google XML Serialization for more information.
         /// </summary>
+        /// <example>
+        /// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
+        /// You can choose to save the resulting XML as a string, or to save it to a file.  This function Loads it from a 
+        /// resource file (one which has been added to Properties.Resources.)  The corresponding write function: 
+        /// <see cref="WriteToXmlFile{T}(string, T)"/> writes to a file that is outside of Properties.Resources; the
+        /// resources of a program are read-only.  Once you write to a file, you can drag the resulting XML into your project
+        /// and load it from there.  If you want to load from an XML file that is not a resource, use <see cref="ReadFromXmlFile{T}(string)"/>
+        /// <para/>Here is code to create an item and save it to a file.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = new MyClass();
+        ///     MyVariable.Name = "StoreThis!";
+        ///     
+        ///     SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
+        /// </code>
+        /// Now that we have an XML file, we drag that file into our project so that it shows up in our Properties.Resources
+        /// and then we can use this code to load it.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = SpriteDatabase.LoadObjectFromXmlFile&lt;MyClass&gt;("xml_file",Properties.Resources.ResourceManager);
+        ///     Console.WriteLine(MyVariable.Name);
+        /// </code>
+        /// </example>
         /// <typeparam name="T">The type of object to load.  It could be something as simple as an int, a class, or a list of classes.</typeparam>
         /// <param name="XMLResourceToLoad">The resource item to load.  If you would access it like: properties.resources.myFile,
         /// the correct value to put here would be "myFile"</param>
@@ -376,6 +459,25 @@ namespace SpriteLibrary
         /// If there are public properties/variables that you do not want written to the file, decorate them with the [XmlIgnore] attribute.
         /// Object type must have a parameterless constructor.
         /// </summary>
+        /// <example>
+        /// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
+        /// You can choose to save the resulting XML as a string, or to save it to a file.  This function 
+        /// writes to a file that is outside of Properties.Resources; the
+        /// resources of a program are read-only.  Once you write to a file, you can drag the resulting XML into your project
+        /// and load it from there.  If you want to load from an XML file that is not a resource, use <see cref="ReadFromXmlFile{T}(string)"/>
+        /// <para/>Here is code to create an item and save it to a file.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = new MyClass();
+        ///     MyVariable.Name = "StoreThis!";
+        ///     
+        ///     SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
+        /// </code>
+        /// Now that we have an XML file, we can use this code to load it.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = SpriteDatabase.ReadFromXmlFile&lt;MyClass&gt;("c:\xml_file.xml");
+        ///     Console.WriteLine(MyVariable.Name);
+        /// </code>
+        /// </example>
         /// <typeparam name="T">The type of object being written to the file.</typeparam>
         /// <param name="filePath">The file path to write the object instance to.</param>
         /// <param name="objectToWrite">The object instance to write to the file.</param>
@@ -399,6 +501,22 @@ namespace SpriteLibrary
         /// Reads an object instance from an XML file.
         /// <para>Object type must have a parameterless constructor.</para>
         /// </summary>
+        /// <example>
+        /// XML Serialization takes an object (a class, a variable, or whatever) and will store any public values in XML.
+        /// You can choose to save the resulting XML as a string, or to save it to a file.  This function 
+        /// reads in a file that probably has been written by <see cref="SpriteDatabase.WriteToXmlFile{T}(string, T)"/>.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = new MyClass();
+        ///     MyVariable.Name = "StoreThis!";
+        ///     
+        ///     SpriteDatabase.WriteToXmlFile&lt;MyClass&gt;("c:\xml_file.xml", MyClass);
+        /// </code>
+        /// Now that we have an XML file, we can use this code to load it.
+        /// <code Lang="C#">
+        ///     MyClass MyVariable = SpriteDatabase.ReadFromXmlFile&lt;MyClass&gt;("c:\xml_file.xml");
+        ///     Console.WriteLine(MyVariable.Name);
+        /// </code>
+        /// </example>
         /// <typeparam name="T">The type of object to read from the file.</typeparam>
         /// <param name="filePath">The file path to read the object instance from.</param>
         /// <returns>Returns a new instance of the object read from the XML file.</returns>