Lots more documentation updates for the sprite controller

SpriteLibrary/Sprite.cs

@@ -137,10 +137,25 @@ namespace SpriteLibrary
         private Sprite MovingToSprite = null;
 
         private bool _AutomaticallyMoves = false; //Does the sprite move in the direction it has been set?
+
         /// <summary>
         /// Determine if the sprite automatically moves (you need to give it a direction [using one of the
         /// SetSpriteDirection functions] and speed [MovementSpeed = X] also)
         /// </summary>     
+        /// <example>
+        /// Here is a short bit of code, showing how AutomaticallyMoves is part of the bigger picture.  You
+        /// need to set the direction (or use a <see cref="Sprite.MoveTo(List{Point})"/> function), as well
+        /// as setting the speed.
+        /// <code lang="C#">
+        ///    Sprite NewSprite = MySpriteController.DuplicateSprite("Dragon");
+        ///    NewSprite.AutomaticallyMoves = true;
+        ///    NewSprite.CannotMoveOutsideBox = true;
+        ///    NewSprite.SpriteHitsPictureBox += SpriteBounces;
+        ///    NewSprite.SetSpriteDirectionDegrees(90);
+        ///    NewSprite.PutBaseImageLocation(new Point(startx, starty));
+        ///    NewSprite.MovementSpeed = speed;
+        /// </code>
+        /// </example>
         public bool AutomaticallyMoves
         {
             get { return _AutomaticallyMoves; }
@@ -926,6 +941,22 @@ namespace SpriteLibrary
         /// to place a Sprite somewhere.  It is the easiest way to track things.  But, if you are
         /// doing something using mouse-click coordinates, you want to use PutPictureBoxLocation
         /// </summary>
+        /// <example>
+        /// Here is a short bit of code, showing how PutBaseImageLocation is part of the bigger picture.  You
+        /// may want to tell it to <see cref="AutomaticallyMoves"/>, 
+        /// set the direction <see cref="SetSpriteDirectionDegrees(double)"/>
+        /// (or use a <see cref="Sprite.MoveTo(List{Point})"/> function), as well
+        /// as setting the speed (<see cref="MovementSpeed"/>).
+        /// <code lang="C#">
+        ///    Sprite NewSprite = MySpriteController.DuplicateSprite("Dragon");
+        ///    NewSprite.AutomaticallyMoves = true;
+        ///    NewSprite.CannotMoveOutsideBox = true;
+        ///    NewSprite.SpriteHitsPictureBox += SpriteBounces;
+        ///    NewSprite.SetSpriteDirectionDegrees(90);
+        ///    NewSprite.PutBaseImageLocation(new Point(startx, starty));
+        ///    NewSprite.MovementSpeed = speed;
+        /// </code>
+        /// </example>
         /// <param name="NewLocationOnImage">The new point on the Image</param>
         public void PutBaseImageLocation(Point NewLocationOnImage)
         {
@@ -948,7 +979,7 @@ namespace SpriteLibrary
         /// Put the Sprite at a specified location, using the dimentions of the BackgroundImage.
         /// Unless you are using coordinates you have gotten from a mouse-click, this is how you want
         /// to place a Sprite somewhere.  It is the easiest way to track things.  But, if you are
-        /// doing something using mouse-click coordinates, you want to use PutPictureBoxLocation
+        /// doing something using mouse-click coordinates, you want to use <see cref="PutPictureBoxLocation(Point)"/>
         /// </summary>
         /// <param name="X">The X location on the background image</param>
         /// <param name="Y">the Y location on the background image</param>
@@ -1219,7 +1250,17 @@ namespace SpriteLibrary
 
         /// <summary>
         /// Tell the sprite to kill itself.  It will erase itself and then
-        /// be removed from the spritelist.  Then it will be gone forever.
+        /// be removed from the spritelist.  Then it will be gone forever.  Sort-of.  You see, so long as
+        /// you still have a variable that has the sprite, that variable will still be able to reference
+        /// the Sprite.  The <see cref="Sprite.Destroying"/> value will say that it is trying to be destroyed,
+        /// but you can still accidentally do something.  You really want to set your variables to null once
+        /// you destroy something:
+        /// <example>
+        /// <code LANG="C#">
+        /// MySprite.Destroy();
+        /// MySprite = null;
+        /// </code>
+        /// </example>
         /// </summary>
         public void Destroy()
         {
@@ -1447,6 +1488,19 @@ namespace SpriteLibrary
         /// consideration the movement direction of the destination sprite.  So the moving sprite does need to be
         /// moving a bit faster than the sprite you are trying to hit for it to do so.
         /// </summary>
+        /// <example>
+        /// In this example we are creating a "heat seaking" missile that will find the target sprite, regardless
+        /// of where it moves.  The missile will move in a straight line from where it is to where the target sprite is,
+        /// regardless of where the target sprite moves to.  It readjusts the movement direction quite often, so it
+        /// is very difficult to dodge.  Use this only when you really want the thing to hit.
+        /// <code lang="C#">
+        ///    Sprite NewSprite = MySpriteController.DuplicateSprite("Missile");
+        ///    NewSprite.AutomaticallyMoves = true;
+        ///    NewSprite.PutBaseImageLocation(new Point(startx, starty));
+        ///    NewSprite.MoveTo(TargetSprite);
+        ///    NewSprite.MovementSpeed = speed;
+        /// </code>
+        /// </example>
         /// <param name="Destination">The sprite we are trying to hit</param>
         public void MoveTo(Sprite Destination)
         {
@@ -1466,6 +1520,17 @@ namespace SpriteLibrary
         /// that point at the MovementSpeed you have set.  When it gets to the point, the SpriteArrivedAtEndPoint event
         /// will fire off.  Also, the SpriteReachedEnd bool will be true.
         /// </summary>
+        /// <example>
+        /// In this example, we are creating a missile sprite and shooting it to where the target sprite
+        /// currently is.  The target may move away and we might miss it entirely.
+        /// <code lang="C#">
+        ///    Sprite NewSprite = MySpriteController.DuplicateSprite("Missile");
+        ///    NewSprite.AutomaticallyMoves = true;
+        ///    NewSprite.PutBaseImageLocation(new Point(startx, starty));
+        ///    NewSprite.MoveTo(TargetSprite.BaseImageLocation);
+        ///    NewSprite.MovementSpeed = speed;
+        /// </code>
+        /// </example>
         /// <param name="Destination">An image-point that the sprite will move to.</param>
         public void MoveTo(Point Destination)
         {
@@ -1481,6 +1546,23 @@ namespace SpriteLibrary
         /// event is triggered.  While the sprite is moving, the SpriteReachedEndPoint attribute is set to false.  When it has
         /// arrived, it is set to true.
         /// </summary>
+        /// <example>
+        /// In this example, we are creating a missile sprite and giving it a path to follow to get where we want it
+        /// to go.  The path is somewhat curved.  The missile will fly straight between each of the different points listed.
+        /// <code lang="C#">
+        ///    Sprite NewSprite = MySpriteController.DuplicateSprite("Missile");
+        ///    NewSprite.AutomaticallyMoves = true;
+        ///    NewSprite.PutBaseImageLocation(new Point(100, 100));
+        ///    List&lt;Point&gt; MyWaypoints = new List&lt;Point&gt;();
+        ///    MyWaypoints.Add(new Point(100,100));
+        ///    MyWaypoints.Add(new Point(120, 90));
+        ///    MyWaypoints.Add(new Point(130, 80));
+        ///    MyWaypoints.Add(new Point(140, 90));
+        ///    MyWaypoints.Add(new Point(180,100));
+        ///    NewSprite.MoveTo(TargetSprite.BaseImageLocation);
+        ///    NewSprite.MovementSpeed = speed;
+        /// </code>
+        /// </example>
         /// <param name="DestinationList">A list of Image-Points that the sprite will follow, one after the other</param>
         public void MoveTo(List<Point> DestinationList)
         {