Fixing some StyleCop violations.

trunk/SecondLife/SecondLifeMain.cs

@@ -44,6 +44,7 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Text;
 using System.Text.RegularExpressions;
 
@@ -55,13 +56,44 @@ using System.Text.RegularExpressions;
 namespace LSLEditor
 {
 	/// <summary>
-	/// Enumeration of Communication Types that the host understands
+	/// Enumeration of Communication Types that the host understands.
 	/// </summary>
 	public enum CommunicationType
 	{
-		Whisper, Say, Shout, OwnerSay, RegionSay, RegionSayTo
+		/// <summary>
+		/// Indicates the message can be heard only within 5m.
+		/// </summary>
+		Whisper, 
+
+		/// <summary>
+		/// Indicates the message can be heard only within 20m.
+		/// </summary>
+		Say, 
+
+		/// <summary>
+		/// Indicates the message can be heard only within 100m.
+		/// </summary>
+		Shout, 
+
+		/// <summary>
+		/// Indicates the message can be only heard by the owner any where within the same simulator.
+		/// </summary>
+		OwnerSay, 
+
+		/// <summary>
+		/// Indicates the message can be heard any where within the same simulator.
+		/// </summary>
+		RegionSay, 
+
+		/// <summary>
+		/// Indicates the message can be heard any where within the same simulator, by a specific object.
+		/// </summary>
+		RegionSayTo
 	}
 
+	/// <summary>
+	/// Partial definition of SecondLife class to handle running scripts.
+	/// </summary>
 	public partial class SecondLife
 	{
 		/// <summary>
@@ -81,7 +113,7 @@ namespace LSLEditor
 		private DateTime dtDateTimeScriptStarted;
 
 		/// <summary>
-		/// Contains a boolean value indicating wether this object accepts other items to be dropped into it.
+		/// Contains a boolean value indicating whether this object accepts other items to be dropped into it.
 		/// </summary>
 		private bool blnAllowDrop = false;
 
@@ -100,25 +132,63 @@ namespace LSLEditor
 		/// </summary>
 		private Float fVolume;
 
+		/// <summary>
+		/// Name of the object/prim.
+		/// </summary>
 		private String sObjectName;
+
+		/// <summary>
+		/// URL for parcel's music stream.
+		/// </summary>
 		private String sParcelMusicURL;
+
+		/// <summary>
+		/// Position of object/prim  placement in a simulator.
+		/// </summary>
 		private vector vPosition;
+
+		/// <summary>
+		/// Rotation of the object/prim's placement in the simulator.
+		/// </summary>
 		private rotation rRotation;
+
+		/// <summary>
+		/// Local rotation of the prim with respect to the object root.
+		/// </summary>
 		private rotation rRotationlocal;
+
+		/// <summary>
+		/// Scale of the object/prim.
+		/// </summary>
 		private vector vScale;
+
+		/// <summary>
+		/// Text for the "Sit" entry on object menu.
+		/// </summary>
 		private String sSitText;
+
+		/// <summary>
+		/// Radius that sound may be heard around the object/prim.
+		/// </summary>
 		private Float fSoundRadius;
 
+		/// <summary>
+		/// Region Coordinates of the simulator's bottom-left corner.
+		/// </summary>
 		private vector vRegionCorner;
 
+		/// <summary>
+		/// Parameter passed to the script on startup.
+		/// </summary>
 		private integer iStartParameter;
 
 		#endregion
 
 		#region Constructor
 		/// <summary>
-		/// Initialises the <see cref="SecondLife"/> class.
+		/// Initialises a new instance of the <see cref="SecondLife"/> class.
 		/// </summary>
+		[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText", Justification = "Reviewed.")]
 		public SecondLife()
 		{
 			this.host = null;
@@ -141,12 +211,21 @@ namespace LSLEditor
 		#endregion
 
 		#region Properties
+
+		/// <summary>
+		/// Gets the position of the object within the simulator.
+		/// </summary>
+		/// <value>Gets the vPosition data member.</value>
 		public vector GetLocalPos
 		{
 			// TODO change this to use a call to llGetLocalPos specifying NOT to be Verbose. After all functions have been changed to allow verbose/silent option.
 			get { return vPosition; }
 		}
 		
+		/// <summary>
+		/// Gets or sets the SecondLifeHost object.
+		/// </summary>
+		/// <value>The host property gets/sets the slhHost data member.</value>
 		public SecondLifeHost host
 		{
 			get { return this.slhHost; }
@@ -155,6 +234,11 @@ namespace LSLEditor
 		#endregion
 		
 		#region internal routines
+		/// <summary>
+		/// Outputs messages during execution of the script.
+		/// </summary>
+		/// <param name="strLine">The text (with possible placeholders) to be output.</param>
+		/// <param name="parameters">Values to be put into corresponding placeholders.</param>
 		private void Verbose(string strLine, params object[] parameters)
 		{
 			if (parameters.Length == 0) {
@@ -164,11 +248,21 @@ namespace LSLEditor
 			}
 		}
 
+		/// <summary>
+		/// Wrapper to call the SecondLifeHost.Chat method.
+		/// </summary>
+		/// <param name="iChannel">Channel for message to be sent on.</param>
+		/// <param name="sText">Text of message to send.</param>
+		/// <param name="ctHow">Type of communication (from CommunicationType enumerator).</param>
 		private void Chat(integer iChannel, string sText, CommunicationType ctHow)
 		{
 			this.host.Chat(this.host, iChannel, this.host.GetObjectName(), this.host.GetKey(), sText, ctHow);
 		}
 
+		/// <summary>
+		/// Method to trigger change in script state.
+		/// </summary>
+		/// <param name="strStateName">Name of state to switch to.</param>
 		public void state(string strStateName)
 		{
 			Verbose("state->" + strStateName);
@@ -181,6 +275,13 @@ namespace LSLEditor
 		#region Helper Functions
 
 		#region List Functions
+		/// <summary>
+		/// Takes the possibly negative value list indexes and corrects them to be absolute indexes.
+		/// </summary>
+		/// <param name="intLength">Length of list.</param>
+		/// <param name="intStart">Start index.</param>
+		/// <param name="intEnd">End index.</param>
+		/// <returns>True, unless an error occurred, then false.</returns>
 		private bool CorrectIt(int intLength, ref int intStart, ref int intEnd)
 		{
 			bool bResult = true;
@@ -207,6 +308,11 @@ namespace LSLEditor
 			return bResult;
 		}
 
+		/// <summary>
+		/// Randomly rearranges the list of items.
+		/// </summary>
+		/// <param name="alCollection">List to shuffle.</param>
+		/// <returns>The reordered list.</returns>
 		public ArrayList RandomShuffle(ArrayList alCollection)
 		{
 			/* We have to copy all items anyway, and there isn't a way to produce the items
@@ -230,6 +336,12 @@ namespace LSLEditor
 			return alCollection;
 		}
 
+		/// <summary>
+		/// Convert a list into an array of buckets containing Stride elements.
+		/// </summary>
+		/// <param name="lSource">List of items.</param>
+		/// <param name="intStride">Number of element for each bucket.</param>
+		/// <returns>The list separated into elements of Stride length.</returns>
 		private ArrayList List2Buckets(list lSource, int intStride)
 		{
 			ArrayList alBuckets = null;
@@ -246,12 +358,18 @@ namespace LSLEditor
 			return alBuckets;
 		}
 
+		/// <summary>
+		/// Converts buckets back into a list.
+		/// </summary>
+		/// <param name="alBuckets">Array of buckets.</param>
+		/// <param name="intStride">Stride value.</param>
+		/// <returns>The items recombined into a simple list.</returns>
 		private list Buckets2List(ArrayList alBuckets, int intStride)
 		{
 			object[] items = new object[alBuckets.Count * intStride];
 			for (int intI = 0; intI < alBuckets.Count; intI++) {
 				for (int intJ = 0; intJ < intStride; intJ++) {
-					items[intI * intStride + intJ] = ((object[])alBuckets[intI])[intJ];
+					items[(intI * intStride) + intJ] = ((object[])alBuckets[intI])[intJ];
 				}
 			}
 			return new list(items);
@@ -262,17 +380,27 @@ namespace LSLEditor
 		/// </summary>
 		private class BucketComparer : IComparer
 		{
+			/// <summary>
+			/// True/false parameter indicating whether the comparison should be done in ascending or descending order.
+			/// </summary>
 			private integer iAscending;
 
 			/// <summary>
-			/// Initialises the <see cref="BucketComparer"/> class.
+			/// Initialises a new instance of the <see cref="BucketComparer"/> class.
 			/// </summary>
 			/// <param name="ascending"></param>
+			[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText", Justification = "Reviewed.")]
 			public BucketComparer(integer ascending)
 			{
 				this.iAscending = ascending;
 			}
 
+			/// <summary>
+			/// Perform the comparison between two objects.
+			/// </summary>
+			/// <param name="x">First object.</param>
+			/// <param name="y">Second object.</param>
+			/// <returns>An integer (-1, 0, or 1), indicating whether the first item is less than, same as, or greater than the second.</returns>
 			public int Compare(object x, object y)
 			{
 				int iResult = 0;
@@ -305,6 +433,15 @@ namespace LSLEditor
 		#endregion
 
 		#region String Functions
+
+		/// <summary>
+		/// Takes a string and splits it into a list based upon separators (which are not kept) and spacers (which are).
+		/// </summary>
+		/// <param name="sSource">The source text.</param>
+		/// <param name="lSeparators">Separators to split on.</param>
+		/// <param name="lSpacers">Spacers to split on.</param>
+		/// <param name="blnKeepNulls">True/false indicating whether nulls are kept in the resulting list.</param>
+		/// <returns>A new list of the split string.</returns>
 		private list ParseString(String sSource, list lSeparators, list lSpacers, bool blnKeepNulls)
 		{
 			list lResult = new list();
@@ -358,12 +495,22 @@ namespace LSLEditor
 			return lResult;
 		}
 
+		/// <summary>
+		/// Convert string to Base64 representation.
+		/// </summary>
+		/// <param name="strText">Source string.</param>
+		/// <returns>Base64 encoding of the source string.</returns>
 		private string StringToBase64(string strText)
 		{
 			byte[] data = Encoding.UTF8.GetBytes(strText);
 			return Convert.ToBase64String(data);
 		}
 
+		/// <summary>
+		/// Converts Base64 encoded string back to UTF-8.
+		/// </summary>
+		/// <param name="strText">Base64 encoded string.</param>
+		/// <returns>UTF-8 string.</returns>
 		private string Base64ToString(string strText)
 		{
 			byte[] data = Convert.FromBase64String(strText);
@@ -374,6 +521,12 @@ namespace LSLEditor
 			return Encoding.UTF8.GetString(data, 0, intLen);
 		}
 
+		/// <summary>
+		/// Performs the lookup.
+		/// </summary>
+		/// <param name="s">String source.</param>
+		/// <param name="intIndex">Byte within string.</param>
+		/// <returns>The Base64 value of the element.</returns>
 		private int LookupBase64(string s, int intIndex)
 		{
 			int intReturn = 0;
@@ -390,6 +543,9 @@ namespace LSLEditor
 			return intReturn;
 		}
 
+		/// <summary>
+		/// Pre-generated matrix for quicker lookup.
+		/// </summary>
 ////[SuppressMessage("StyleCop.CSharp.OrderingRules", "SA1204:StaticElementsMustAppearBeforeInstanceElements", Justification = "Stays with other string functions.")]
 		private static readonly int[] FastLookupBase64 =
 			{ // 0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
@@ -412,11 +568,26 @@ namespace LSLEditor
 		#endregion
 
 		#region Math Functions
+
+		/// <summary>
+		/// Performs (iA ** iB) % iC.
+		/// </summary>
+		/// <param name="iA">Base value.</param>
+		/// <param name="iB">Exponent value .</param>
+		/// <param name="iC">Modulus value.</param>
+		/// <returns>The calculated result.</returns>
 		private integer ModPow1(integer iA, integer iB, integer iC)
 		{
 			return (int)Math.Pow((int)iA, (int)iB & (int)0xffff) % (int)iC;
 		}
 
+		/// <summary>
+		/// Performs the llModPow2() function.
+		/// </summary>
+		/// <param name="iValueX">Value one.</param>
+		/// <param name="iValueY">Value two.</param>
+		/// <param name="iModulus">The modulus value.</param>
+		/// <returns>The calculated result.</returns>
 		private integer ModPow2(integer iValueX, integer iValueY, integer iModulus)
 		{
 			integer iResult = 0;
@@ -439,6 +610,11 @@ namespace LSLEditor
 		}
 		#endregion Math Functions
 
+		/// <summary>
+		/// Used by llListStatistics in generating the statistics.
+		/// </summary>
+		/// <param name="lInput">List of numbers (mixed types possible) to use.</param>
+		/// <returns>The numbers added together as a Float type.</returns>
 		private List<double> GetListOfNumbers(list lInput)
 		{
 			List<double> lResult = new List<double>();
@@ -465,6 +641,11 @@ namespace LSLEditor
 			return lResult;
 		}
 
+		/// <summary>
+		/// Calculates the mean of the supplied numbers.
+		/// </summary>
+		/// <param name="data">Array of numbers.</param>
+		/// <returns>The mean of the supplied numbers as a double type.</returns>
 		private double GetAverage(double[] data)
 		{
 			try {
@@ -478,6 +659,11 @@ namespace LSLEditor
 			}
 		}
 
+		/// <summary>
+		/// Calculates standard deviation.
+		/// </summary>
+		/// <param name="dblNumbers">Array of numbers to work with.</param>
+		/// <returns>The standard deviation of the supplied numbers as a double type.</returns>
 		public double GetStandardDeviation(double[] dblNumbers)
 		{
 			double dblSum = 0.0, dblSumOfSqrs = 0.0;
@@ -490,9 +676,15 @@ namespace LSLEditor
 			return Math.Sqrt(dblTopSum / (dblN * (dblN - 1)));
 		}
 
+		/// <summary>
+		/// Performs division, only if both values are non-zero.
+		/// </summary>
+		/// <param name="dblValue1">First number.</param>
+		/// <param name="dblValue2">Second number.</param>
+		/// <returns>The result of the division, or zero if not performed.</returns>
 		private double SafeDivide(double dblValue1, double dblValue2)
 		{
-			double dblResult = 0;
+			double dblResult = 0.0F;
 			try {
 				if ((dblValue1 != 0) && (dblValue2 != 0)) {
 					dblResult = dblValue1 / dblValue2;
@@ -502,6 +694,11 @@ namespace LSLEditor
 			return dblResult;
 		}
 
+		/// <summary>
+		/// Takes a hexadecimal representation of a number and coverts it to an integer.
+		/// </summary>
+		/// <param name="b">Byte to convert.</param>
+		/// <returns>Integer value of the supplied byte.</returns>
 		private byte HexToInt(byte b)
 		{
 			byte bResult;