Documentation for the SpriteDatabase

SpriteLibrary/SpriteDatabase.cs

@@ -123,6 +123,10 @@ namespace SpriteLibrary
                 SpriteInfoList = new List<SpriteInfo>(); //make an empty one so things do not explode.
         }
 
+        /// <summary>
+        /// Return a list of the SpriteNames that this Database knows how to create.
+        /// </summary>
+        /// <returns>A list of strings, each one is the name of a sprite</returns>
         public List<string> SpriteNames()
         {
             List<string> theNames = new List<string>();
@@ -141,6 +145,11 @@ namespace SpriteLibrary
             return false;
         }
 
+        /// <summary>
+        /// Open a Sprite Edit Window.  This window does not let you draw a sprite.  What it does is to help
+        /// you define your sprites and makes the process of using Sprites in your program a lot easier.
+        /// </summary>
+        /// <param name="FirstItemIndex"></param>
         public void OpenEditWindow(int FirstItemIndex=-1)
         {
             SpriteEntryForm SEF = new SpriteEntryForm(this, SpriteInfoList, SnapGridSize);
@@ -152,6 +161,19 @@ namespace SpriteLibrary
         #endregion
         
         #region General Functions
+        /// <summary>
+        /// This function returns an image from the Properties.Resources.  If we tell it to UseSmartImages, then
+        /// it caches the image in memory.  This makes it a little faster to return.  If you have a lot of sprites
+        /// to load, using this system can speed up things a fair bit.  But, try to remember not to change the
+        /// image that this returns unless you duplicate it first.  Otherwise you will end up changing the image
+        /// for all the other times you reference it.  This is usualy a bad thing.
+        /// </summary>
+        /// <param name="Name">The string name of the image.  If your image is usually named
+        /// Properties.Resources.mySpriteImage, you will want to have "mySpriteImage" as the Name passed
+        /// to GetImageFromName</param>
+        /// <param name="UseSmartImages">A parameter stating whether we should cache the image in memory
+        /// or simply retrieve it from the resource manager.</param>
+        /// <returns></returns>
         public Image GetImageFromName(string Name, bool UseSmartImages)
         {
             Image MyImage = null;
@@ -181,7 +203,16 @@ namespace SpriteLibrary
             return MyImage;
         }
 
-        public Sprite SmartDuplicateSprite(SpriteController theController, string SpriteName, bool UseSmartImages = true)
+        /// <summary>
+        /// This code is mostly handled by the sprite controller.  If the SpriteController has a SpriteDatabase
+        /// registered, then it will automatically ask the SpriteDatabase to create any sprite it does not already
+        /// have.
+        /// </summary>
+        /// <param name="theController">The controller that will manage the newly created Sprite</param>
+        /// <param name="SpriteName">The name of the sprite to look up and then create</param>
+        /// <param name="UseSmartImages">Whether or not we should cache images to give a very small increase in speed</param>
+        /// <returns></returns>
+        internal Sprite SmartDuplicateSprite(SpriteController theController, string SpriteName, bool UseSmartImages = true)
         {
             Sprite DestSprite = theController.DuplicateSprite(SpriteName);
             if (DestSprite != null) return DestSprite;
@@ -279,6 +310,15 @@ namespace SpriteLibrary
             }
         }
 
+        /// <summary>
+        /// This is a generic function which the SpriteDatabase uses.  It does XML Serialization of most anything,
+        /// and generates an XML String.  XML Serialization will take any public value of a public class and 
+        /// make an XML entry for it.  It is a very convienent way to save data.  You can "Deserialize" the value
+        /// with the <see cref="SpriteDatabase.ReadFromXmlString{T}(string)">ReadFromXMLString</see> function.
+        /// </summary>
+        /// <typeparam name="T">The type of the item that you are trying to serialize</typeparam>
+        /// <param name="toSerialize">the variable you are trying to turn into XML</param>
+        /// <returns>An XML string</returns>
         public static string WriteToXMLString<T>(T toSerialize)
         {
             XmlSerializer xmlSerializer = new XmlSerializer(toSerialize.GetType());
@@ -289,6 +329,16 @@ namespace SpriteLibrary
                 return textWriter.ToString();
             }
         }
+
+        /// <summary>
+        /// This is a generic function which the SpriteDatabase uses.  It does XML Deserialization of most anything,
+        /// and generates an XML String.  XML Serialization will take any public value of a public class and 
+        /// make an XML entry for it.  It is a very convienent way to save and retrieve data.  You can "Serialize" the value
+        /// with the <see cref="SpriteDatabase.WriteToXMLString{T}(T)">WriteToXMLString</see> function.
+        /// </summary>
+        /// <typeparam name="T">The type of the item that you are trying to deserialize</typeparam>
+        /// <param name="toDeserialize">an XML string, of something you serialized previously</param>
+        /// <returns>An object of type T</returns>
         public static T ReadFromXmlString<T>(string toDeserialize) where T : new()
         {
             XmlSerializer xmlSerializer = new XmlSerializer(typeof(T));
@@ -296,6 +346,14 @@ namespace SpriteLibrary
                 return (T)xmlSerializer.Deserialize(textReader);
         }
 
+        /// <summary>
+        /// This is an inefficient, but simple function to clone a class.  It works by serializing an item
+        /// to a string, and then deserializing it into a class.  The end result is that any value which is
+        /// publically visible is duplicated, but it is a completely separate class from the original.
+        /// </summary>
+        /// <typeparam name="T">The type of the item to clone</typeparam>
+        /// <param name="ObjectToClone">The actual object to clone</param>
+        /// <returns>A duplicate of the original</returns>
         public static T CloneByXMLSerializing<T>(T ObjectToClone)
         {
             XmlSerializer xmlSerializer = new XmlSerializer(typeof(T));