small doc fixes so it looks better on the wiki

svn path=/branches/mono-2-6/mono-tools/; revision=148783

18 files changed, 198 insertions, 128 deletions

diff --git a/gendarme/rules/Gendarme.Rules.BadPractice/OnlyUseDisposeForIDisposableTypesRule.cs b/gendarme/rules/Gendarme.Rules.BadPractice/OnlyUseDisposeForIDisposableTypesRule.cs
index b5ea1290..cdec944b 100644
--- a/gendarme/rules/Gendarme.Rules.BadPractice/OnlyUseDisposeForIDisposableTypesRule.cs
+++ b/gendarme/rules/Gendarme.Rules.BadPractice/OnlyUseDisposeForIDisposableTypesRule.cs
@@ -64,6 +64,7 @@ namespace Gendarme.Rules.BadPractice {
 	/// </example>
 	/// <example>
 	/// Good example:
+	/// <code>
 	/// internal sealed class Worker
 	/// {
 	/// 	// This class uses one or more temporary files to do its work.
@@ -78,9 +79,9 @@ namespace Gendarme.Rules.BadPractice {
 	/// 		files.Clear ();
 	/// 	}
 	/// }
-	/// <code>
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("A type has a method named Dispose, but does not implement IDisposable.")]
 	[Solution ("Rename the method or implement IDisposable.")]
diff --git a/gendarme/rules/Gendarme.Rules.BadPractice/PreferSafeHandleRule.cs b/gendarme/rules/Gendarme.Rules.BadPractice/PreferSafeHandleRule.cs
index 62f4c062..ae3733fd 100644
--- a/gendarme/rules/Gendarme.Rules.BadPractice/PreferSafeHandleRule.cs
+++ b/gendarme/rules/Gendarme.Rules.BadPractice/PreferSafeHandleRule.cs
@@ -69,9 +69,9 @@ namespace Gendarme.Rules.BadPractice {
 	/// 
 	/// // If cleaning up the native resource in a timely manner is important you can
 	/// // implement IDisposable.
-	/// public sealed class Database
-	/// {
-	/// 	~Database () {
+	/// public sealed class Database {
+	/// 	~Database ()
+	/// 	{
 	/// 		// This will execute even if the ctor throws so it is important to check
 	/// 		// to see if the fields are initialized.
 	/// 		if (m_database != IntPtr.Zero) {
@@ -82,13 +82,13 @@ namespace Gendarme.Rules.BadPractice {
 	/// 	public Database (string path)
 	/// 	{		
 	/// 		NativeMethods.OpenFlags flags = NativeMethods.OpenFlags.READWRITE | NativeMethods.OpenFlags.CREATE;
-	/// 		NativeMethods.Error err = NativeMethods.sqlite3_open_v2 (path, out m_database, flags, IntPtr.Zero);
+	/// 		int err = NativeMethods.sqlite3_open_v2 (path, out m_database, flags, IntPtr.Zero);
 	/// 		// handle errors
 	/// 	}
 	/// 	
 	/// 	// exec and query methods would go here
 	/// 							
-	/// 	[SuppressUnmanagedCodeSecurity ()]
+	/// 	[SuppressUnmanagedCodeSecurity]
 	/// 	private static class NativeMethods {
 	/// 		[Flags]
 	/// 		public enum OpenFlags : int {
@@ -98,17 +98,11 @@ namespace Gendarme.Rules.BadPractice {
 	/// 			// ...
 	/// 		}
 	/// 		
-	/// 		public enum Error : int {
-	/// 			OK = 0, 
-	/// 			ERROR = 1,
-	/// 			// ...
-	/// 		}
-	/// 						
 	/// 		[DllImport ("sqlite3")]
-	/// 		public static extern Error sqlite3_close (IntPtr db);
+	/// 		public static extern int sqlite3_close (IntPtr db);
 	/// 					
 	/// 	   	[DllImport ("sqlite3")]
-	/// 	    public static extern Error sqlite3_open_v2 (string fileName, out IntPtr db, OpenFlags flags, IntPtr module);
+	/// 		public static extern int sqlite3_open_v2 (string fileName, out IntPtr db, OpenFlags flags, IntPtr module);
 	/// 	}
 	/// 	
 	///     private IntPtr m_database;
@@ -141,17 +135,17 @@ namespace Gendarme.Rules.BadPractice {
 	/// 	private sealed class SqlitePtr : SafeHandle {
 	/// 		public SqlitePtr (string path, NativeMethods.OpenFlags flags) : base (IntPtr.Zero, true)
 	/// 		{		
-	/// 			NativeMethods.Error err = NativeMethods.sqlite3_open_v2 (path, out handle, flags, IntPtr.Zero);
+	/// 			int err = NativeMethods.sqlite3_open_v2 (path, out handle, flags, IntPtr.Zero);
 	/// 			// handle errors
 	/// 		}
 	/// 		
-	/// 		public override bool IsInvalid 
-	/// 		{ 
-	/// 			get { return handle == IntPtr.Zero; }
+	/// 		public override bool IsInvalid { 
+	/// 			get {
+	/// 				return (handle == IntPtr.Zero);
+	/// 			}
 	/// 		}
 	/// 		
-	/// 		// This will not be called if the handle is invalid. Note that this
-	/// 		// method should not throw.
+	/// 		// This will not be called if the handle is invalid. Note that this method should not throw.
 	/// 		[ReliabilityContract (Consistency.WillNotCorruptState, Cer.MayFail)]
 	/// 		protected override bool ReleaseHandle ()
 	/// 		{
@@ -160,7 +154,7 @@ namespace Gendarme.Rules.BadPractice {
 	/// 		}
 	/// 	}
 	/// 
-	/// 	[SuppressUnmanagedCodeSecurity ()]
+	/// 	[SuppressUnmanagedCodeSecurity]
 	/// 	private static class NativeMethods {
 	/// 		[Flags]
 	/// 		public enum OpenFlags : int {
@@ -170,24 +164,19 @@ namespace Gendarme.Rules.BadPractice {
 	/// 			// ...
 	/// 		}
 	/// 		
-	/// 		public enum Error : int {
-	/// 			OK = 0, 
-	/// 			ERROR = 1,
-	/// 			// ...
-	/// 		}
-	/// 		
 	/// 		[DllImport ("sqlite3")]
-	/// 		public static extern Error sqlite3_close (SqlitePtr db);
+	/// 		public static extern int sqlite3_close (SqlitePtr db);
 	/// 				
 	/// 		// Open must take an IntPtr but all other methods take a type safe SqlitePtr.
 	/// 		[DllImport ("sqlite3")]
-	/// 		public static extern Error sqlite3_open_v2 (string fileName, out IntPtr db, OpenFlags flags, IntPtr module);
+	/// 		public static extern int sqlite3_open_v2 (string fileName, out IntPtr db, OpenFlags flags, IntPtr module);
 	/// 	}
 	/// 
 	/// 	private SqlitePtr m_database;
 	/// }
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("The type uses System.IntPtr or System.UIntPtr instead of System.Runtime.InteropServices.SafeHandle.")]
 	[Solution ("Consider changing the code to use SafeHandle.")]
diff --git a/gendarme/rules/Gendarme.Rules.Concurrency/DoNotUseThreadStaticWithInstanceFieldsRule.cs b/gendarme/rules/Gendarme.Rules.Concurrency/DoNotUseThreadStaticWithInstanceFieldsRule.cs
index aeff206d..af1beeb0 100644
--- a/gendarme/rules/Gendarme.Rules.Concurrency/DoNotUseThreadStaticWithInstanceFieldsRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Concurrency/DoNotUseThreadStaticWithInstanceFieldsRule.cs
@@ -39,7 +39,7 @@ using Gendarme.Framework.Rocks;
 namespace Gendarme.Rules.Concurrency {
 
 	/// <summary>
-	/// This rule will fire if an instance field is decorated with System.ThreadStaticAttribute. 
+	/// This rule will fire if an instance field is decorated with a <c>[ThreadStatic]</c> attribute. 
 	/// This is an error because the attribute will only work with static fields.
 	/// </summary>
 	/// <example>
@@ -78,6 +78,7 @@ namespace Gendarme.Rules.Concurrency {
 	/// } 
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("An instance field is decorated with System.ThreadStaticAttribute.")]
 	[Solution ("ThreadStaticAttribute will only make static fields thread safe. To make an instance field thread safe you need to use techniques like locking or System.Threading.Thread.Thread::AllocateNamedDataSlot.")]
diff --git a/gendarme/rules/Gendarme.Rules.Correctness/AvoidFloatingPointEqualityRule.cs b/gendarme/rules/Gendarme.Rules.Correctness/AvoidFloatingPointEqualityRule.cs
index e62b52b0..8fb8e61c 100644
--- a/gendarme/rules/Gendarme.Rules.Correctness/AvoidFloatingPointEqualityRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Correctness/AvoidFloatingPointEqualityRule.cs
@@ -65,17 +65,17 @@ namespace Gendarme.Rules.Correctness {
 	/// // work as expected.
 	/// public static bool NearlyEqual (double [] lhs, double [] rhs)
 	/// {
-	/// 	if (ReferenceEquals (lhs, rhs))
+	/// 	if (ReferenceEquals (lhs, rhs)) {
 	/// 		return true;
-	/// 		
-	/// 	if (lhs.Length != rhs.Length)
+	/// 	}
+	/// 	if (lhs.Length != rhs.Length) {
 	/// 		return false;
-	/// 		
+	/// 	}
 	/// 	for (int i = 0; i &lt; lhs.Length; ++i) {
-	/// 		if (lhs [i] != rhs [i])
+	/// 		if (lhs [i] != rhs [i]) {
 	/// 			return false;
+	/// 		}
 	/// 	}
-	/// 	
 	/// 	return true;
 	/// }
 	/// </code>
@@ -89,17 +89,17 @@ namespace Gendarme.Rules.Correctness {
 	/// // be scaled accordingly).
 	/// public static bool NearlyEqual (double [] lhs, double [] rhs, double epsilon)
 	/// {
-	/// 	if (ReferenceEquals (lhs, rhs))
+	/// 	if (ReferenceEquals (lhs, rhs)) {
 	/// 		return true;
-	/// 		
-	/// 	if (lhs.Length != rhs.Length)
+	/// 	}
+	/// 	if (lhs.Length != rhs.Length) {
 	/// 		return false;
-	/// 		
+	/// 	}
 	/// 	for (int i = 0; i &lt; lhs.Length; ++i) {
-	/// 		if (Math.Abs (lhs [i] - rhs [i]) &gt; epsilon)
+	/// 		if (Math.Abs (lhs [i] - rhs [i]) &gt; epsilon) {
 	/// 			return false;
+	/// 			}
 	/// 	}
-	/// 	
 	/// 	return true;
 	/// }
 	/// </code>
diff --git a/gendarme/rules/Gendarme.Rules.Correctness/CheckParametersNullityInVisibleMethodsRule.cs b/gendarme/rules/Gendarme.Rules.Correctness/CheckParametersNullityInVisibleMethodsRule.cs
index d0d0732a..49bf8ce3 100644
--- a/gendarme/rules/Gendarme.Rules.Correctness/CheckParametersNullityInVisibleMethodsRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Correctness/CheckParametersNullityInVisibleMethodsRule.cs
@@ -37,6 +37,55 @@ using Gendarme.Framework.Rocks;
 
 namespace Gendarme.Rules.Correctness {
 
+	/// <summary>
+	/// This rule checks if all nullable parameters of visible methods are compared 
+	/// with '''null''' before they get used. This reduce the likelyhood of the runtime
+	/// throwing a <c>NullReferenceException</c>.
+	/// </summary>
+	/// <example>
+	/// Bad example:
+	/// <code>
+	/// [DllImport ("message")]
+	/// internal static extern byte [] Parse (string s, int length);
+	///
+	/// public bool TryParse (string s, out Message m)
+	/// {
+	///	// is 's' is null then 's.Length' will throw a NullReferenceException
+	///	// which a TryParse method should never do
+	///	byte [] data = Parse (s, s.Length);
+	///	if (data == null) {
+	///		m = null;
+	///		return false;
+	///	}
+	///	m = new Message (data);
+	///	return true;
+	/// }
+	/// </code>
+	/// </example>
+	/// <example>
+	/// Good example:
+	/// <code>
+	/// [DllImport ("message")]
+	/// internal static extern byte [] Parse (string s, int length);
+	///
+	/// public bool TryParse (string s, out Message m)
+	/// {
+	///	if (s == null) {
+	///		m = null;
+	///		return false;
+	///	}
+	///	byte [] data = Parse (s, s.Length);
+	///	if (data == null) {
+	///		m = null;
+	///		return false;
+	///	}
+	///	m = new Message (data);
+	///	return true;
+	/// }
+	/// </code>
+	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.2</remarks>
+
 	[Problem ("A visible method does not check its parameter(s) for null values.")]
 	[Solution ("Since the caller is unknown you should always verify all of your parameters to protect yourself.")]
 	[FxCopCompatibility ("Microsoft.Design", "CA1062:ValidateArgumentsOfPublicMethods")]
diff --git a/gendarme/rules/Gendarme.Rules.Correctness/DisposableFieldsShouldBeDisposedRule.cs b/gendarme/rules/Gendarme.Rules.Correctness/DisposableFieldsShouldBeDisposedRule.cs
index f7b866a7..1f63a131 100644
--- a/gendarme/rules/Gendarme.Rules.Correctness/DisposableFieldsShouldBeDisposedRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Correctness/DisposableFieldsShouldBeDisposedRule.cs
@@ -42,9 +42,9 @@ using Gendarme.Framework.Rocks;
 namespace Gendarme.Rules.Correctness {
 
 	/// <summary>
-	/// The rule inspects all fields for disposable types and, if <c>System.IDisposable</c>
-	/// is implemented, checks that the type's <c>Dispose</c> method does indeed call <c>Dispose</c>
-	/// on all disposable fields.
+	/// The rule inspects all fields for disposable types and, if <c>System.IDisposable</c> is
+	/// implemented, checks that the type's <c>Dispose</c> method does indeed call <c>Dispose</c> on
+	/// all disposable fields.
 	/// </summary>
 	/// <example>
 	/// Bad example:
diff --git a/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXPathExpressionRule.cs b/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXPathExpressionRule.cs
index 45d94494..bfac06ce 100644
--- a/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXPathExpressionRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXPathExpressionRule.cs
@@ -67,6 +67,7 @@ namespace Gendarme.Rules.Correctness {
 	/// var xpath = XPathExpression.Compile ("/book[@npages = 100]/@title");
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("An invalid XPath expression string is provided to a method.")]
 	[Solution ("Fix the invalid XPath expression.")]
diff --git a/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXmlStringRule.cs b/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXmlStringRule.cs
index 9a25a241..d9941ebe 100644
--- a/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXmlStringRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Correctness/ProvideValidXmlStringRule.cs
@@ -69,6 +69,7 @@ namespace Gendarme.Rules.Correctness {
 	/// bookElement.InnerXml = "&lt;author&gt;Robert J. Sawyer&lt;/author&gt;";
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("An invalid XML string is provided to a method.")]
 	[Solution ("Fix the invalid XML string.")]
diff --git a/gendarme/rules/Gendarme.Rules.Design/PreferXmlAbstractionsRule.cs b/gendarme/rules/Gendarme.Rules.Design/PreferXmlAbstractionsRule.cs
index b8a72f09..f4108d54 100644
--- a/gendarme/rules/Gendarme.Rules.Design/PreferXmlAbstractionsRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Design/PreferXmlAbstractionsRule.cs
@@ -35,16 +35,20 @@ using Gendarme.Framework.Rocks;
 namespace Gendarme.Rules.Design {
 
 	/// <summary>
-	/// This rule fires if an externally visible method or property uses an XmlDocument, XPathDocument or XmlNode
-	/// argument. The problem with this is that it ties your API to a specific implementation so it is difficult to change
-	/// later. Instead use abstract types like IXPathNavigable, XmlReader, XmlWriter, or subtypes of XmlNode.
+	/// This rule fires if an externally visible method or property uses an <c>XmlDocument</c>, 
+	/// <c>XPathDocument</c> or <c>XmlNode</c> argument. The problem with this is that it ties 
+	/// your API to a specific implementation so it is difficult to change later. Instead use 
+	/// abstract types like <c>IXPathNavigable</c>, <c>XmlReader</c>, <c>XmlWriter</c>, or subtypes
+	/// of <c>XmlNode</c>.
 	/// </summary>
 	/// <example>
 	/// Bad example (property):
 	/// <code>
 	/// public class Application {
 	///	public XmlDocument UserData {
-	///		get { return userData; }
+	///		get {
+	///			return userData;
+	///		}
 	///	}
 	/// }
 	/// </code>
@@ -54,7 +58,9 @@ namespace Gendarme.Rules.Design {
 	/// <code>
 	/// public class Application {
 	///	public IXPathNavigable UserData {
-	///		get { return userData; }
+	///		get {
+	///			return userData;
+	///		}
 	///	}
 	/// }
 	/// </code>
@@ -63,7 +69,8 @@ namespace Gendarme.Rules.Design {
 	/// Bad example (method parameter):
 	/// <code>
 	/// public class Application {
-	///	public bool IsValidUserData (XmlDocument userData) {
+	///	public bool IsValidUserData (XmlDocument userData) 
+	///	{
 	///		/* implementation */
 	///	}
 	/// }
@@ -73,7 +80,8 @@ namespace Gendarme.Rules.Design {
 	/// Good example (method parameter):
 	/// <code>
 	/// public class Application {
-	///	public bool IsValidUserData (XmlReader userData) {
+	///	public bool IsValidUserData (XmlReader userData) 
+	///	{
 	///		/* implementation */
 	///	}
 	/// }
diff --git a/gendarme/rules/Gendarme.Rules.Design/UseCorrectDisposeSignaturesRule.cs b/gendarme/rules/Gendarme.Rules.Design/UseCorrectDisposeSignaturesRule.cs
index bc2e248b..eae98440 100644
--- a/gendarme/rules/Gendarme.Rules.Design/UseCorrectDisposeSignaturesRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Design/UseCorrectDisposeSignaturesRule.cs
@@ -35,11 +35,11 @@ using Gendarme.Framework.Rocks;
 namespace Gendarme.Rules.Design {
 	
 	/// <summary>
-	/// There is a convention that should be followed when implementing IDisposable. Part
+	/// There is a convention that should be followed when implementing <c>IDisposable</c>. Part
 	/// of this convention is that Dispose methods should have specific signatures. In
-	/// particular an IDisposable type's Dispose methods should either be nullary or unary
-	/// with a bool argument, Dispose () should not be virtual, Dispose (bool) should not be 
-	/// public, and unsealed types should have a protected virtual Dispose (bool) method.
+	/// particular an <c>IDisposable</c> type's Dispose methods should either be nullary or unary
+	/// with a bool argument, <c>Dispose ()</c> should not be virtual, <c>Dispose (bool)</c> should
+	/// not be public, and unsealed types should have a <c>protected virtual Dispose (bool)</c> method.
 	/// For more details see: [http://www.bluebytesoftware.com/blog/2005/04/08/DGUpdateDisposeFinalizationAndResourceManagement.aspx].
 	/// </summary>
 	/// <example>
@@ -68,7 +68,10 @@ namespace Gendarme.Rules.Design {
 	/// 		}
 	/// 	}
 	/// 	
-	/// 	protected bool Disposed { get; set; }
+	/// 	protected bool Disposed {
+	/// 		get;
+	/// 		set;
+	/// 	}
 	/// }
 	/// </code>
 	/// </example>
@@ -119,10 +122,14 @@ namespace Gendarme.Rules.Design {
 	/// 		}
 	/// 	}
 	/// 	
-	/// 	protected bool Disposed { get; private set; }
+	/// 	protected bool Disposed {
+	/// 		get; 
+	/// 		private set;
+	/// 	}
 	/// }
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 	
 	[Problem ("An IDisposable type does not conform to the guidelines for its Dispose methods.")]
 	[Solution ("Fix the signature of the methods or add the Dispose (bool) overload.")]
diff --git a/gendarme/rules/Gendarme.Rules.Design/UseFlagsAttributeRule.cs b/gendarme/rules/Gendarme.Rules.Design/UseFlagsAttributeRule.cs
index b99ca194..70d30aa5 100644
--- a/gendarme/rules/Gendarme.Rules.Design/UseFlagsAttributeRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Design/UseFlagsAttributeRule.cs
@@ -39,9 +39,9 @@ namespace Gendarme.Rules.Design {
 
 	/// <summary>
 	/// This rule will fire if an enum's values look like they are intended to
-	/// be composed together with the bitwise OR operator and the enum
-	/// is not decorated with System.FlagsAttribute. Using FlagsAttribute
-	/// will allow System.Enum.ToString to return a better string when 
+	/// be composed together with the bitwise OR operator and the enum is not
+	/// decorated with <c>System.FlagsAttribute</c>. Using <c>FlagsAttribute</c> will
+	/// allow <c>System.Enum.ToString()</c> to return a better string when 
 	/// values are ORed together and helps indicate to readers of the code 
 	/// the intended usage of the enum.
 	/// </summary>
@@ -70,6 +70,7 @@ namespace Gendarme.Rules.Design {
 	/// }
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("The enum seems to be composed of flag values, but is not decorated with [Flags].")]
 	[Solution ("Add [Flags] to the enum,  change the values so that they are not powers of two, or ignore the defect.")]
diff --git a/gendarme/rules/Gendarme.Rules.Exceptions/UseObjectDisposedExceptionRule.cs b/gendarme/rules/Gendarme.Rules.Exceptions/UseObjectDisposedExceptionRule.cs
index e75e50df..d7a14447 100644
--- a/gendarme/rules/Gendarme.Rules.Exceptions/UseObjectDisposedExceptionRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Exceptions/UseObjectDisposedExceptionRule.cs
@@ -110,7 +110,8 @@ namespace Gendarme.Rules.Exceptions {
 	/// }
 	/// </code>
 	/// </example>
-	
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
+
 	[Problem ("A method of an IDisposable type does not throw System.ObjectDisposedException.")]
 	[Solution ("Throw ObjectDisposedException if the object has been disposed.")]
 	public sealed class UseObjectDisposedExceptionRule : Rule, IMethodRule {
diff --git a/gendarme/rules/Gendarme.Rules.Interoperability/DelegatesPassedToNativeCodeMustIncludeExceptionHandlingRule.cs b/gendarme/rules/Gendarme.Rules.Interoperability/DelegatesPassedToNativeCodeMustIncludeExceptionHandlingRule.cs
index ff7c157f..f62d7a9f 100644
--- a/gendarme/rules/Gendarme.Rules.Interoperability/DelegatesPassedToNativeCodeMustIncludeExceptionHandlingRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Interoperability/DelegatesPassedToNativeCodeMustIncludeExceptionHandlingRule.cs
@@ -40,8 +40,8 @@ using Gendarme.Framework.Rocks;
 namespace Gendarme.Rules.Interoperability {
 
 	/// <summary>
-	/// <code>Every delegate which is passed to native code must include an exception 
-	/// block which spans the entire method and has a catch all handler.</code>
+	/// Every delegate which is passed to native code must include an exception 
+	/// block which spans the entire method and has a catch all handler.
 	/// </summary>
 	/// <example>
 	/// Bad example:
@@ -59,36 +59,30 @@ namespace Gendarme.Rules.Interoperability {
 	/// {
 	///	try {
 	///		Console.WriteLine ("{0}", 1);
-	///	} catch {
+	///	}
+	///	catch {
 	///	}
 	/// }
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("Every delegate passed to native code must include an exception block which spans the entire method and has a catch all handler.")]
 	[Solution ("Surround the entire method body with a try/catch block.")]
 	[EngineDependency (typeof (OpCodeEngine))]
 	public class DelegatesPassedToNativeCodeMustIncludeExceptionHandlingRule : Rule, IMethodRule {
-		/// <summary>
-		/// A list of methods which have been verified to be safe to call from native code. 
-		/// </summary>
+		// A list of methods which have been verified to be safe to call from native code. 
 		Dictionary<MethodDefinition, bool> verified_methods;
 		
-		/// <summary>
-		/// A list of methods which have been reported to be unsafe (to not report the same method twice).
-		/// </summary>
+		// A list of methods which have been reported to be unsafe (to not report the same method twice).
 		List<MethodDefinition> reported_methods;
 		
-		/// <summary>
-		/// A list of all the fields which have been passed to pinvokes (as a delegate parameter).
-		/// We report an error if a ld[s]fld stores an unsafe function pointer into any of these fields.
-		/// </summary>
+		// A list of all the fields which have been passed to pinvokes (as a delegate parameter).
+		// We report an error if a ld[s]fld stores an unsafe function pointer into any of these fields.
 		List<FieldDefinition> fields_loads;
 		
-		/// <summary>
-		/// A list of all the fields which have been assigned function pointers.
-		/// We report an error if a pinvoke loads any of these fields.
-		/// </summary>
+		// A list of all the fields which have been assigned function pointers.
+		// We report an error if a pinvoke loads any of these fields.
 		Dictionary<FieldDefinition, List<MethodDefinition>> field_stores;
 				
 		public RuleResult CheckMethod (MethodDefinition method)
@@ -236,9 +230,7 @@ namespace Gendarme.Rules.Interoperability {
 			return Runner.CurrentRuleResult;
 		}
 		
-		/// <summary>
-		/// Verifies that the method is safe to call as a callback from native code.
-		/// </summary>
+		// Verifies that the method is safe to call as a callback from native code.
 		private bool VerifyCallbackSafety (MethodDefinition callback)
 		{
 			bool result;
@@ -342,9 +334,7 @@ namespace Gendarme.Rules.Interoperability {
 			}
 		}
 		
-		/// <summary>
-		/// Parses the ILRange and return all delegate pointers that could end up on the stack as a result of executing that code.
-		/// </summary>
+		// Parses the ILRange and return all delegate pointers that could end up on the stack as a result of executing that code.
 		private List<MethodDefinition> GetDelegatePointers (MethodDefinition method, List<List<MethodDefinition>> locals, ILRange range)
 		{
 			List<MethodDefinition> result = null;
@@ -392,10 +382,8 @@ namespace Gendarme.Rules.Interoperability {
 		}
 		
 		
-		/// <summary>
-		/// Verifies that all methods in the list are safe to call from native code,
-		/// otherwise reports the correspoding result.
-		/// </summary>
+		// Verifies that all methods in the list are safe to call from native code,
+		// otherwise reports the correspoding result.
 		private void VerifyMethods (List<MethodDefinition> pointers)
 		{
 			if (pointers == null)
@@ -405,9 +393,7 @@ namespace Gendarme.Rules.Interoperability {
 				ReportVerifiedMethod (pointer, VerifyCallbackSafety (pointer));
 		}
 		
-		/// <summary>
-		/// Reports the result from verifying the method.
-		/// </summary>
+		// Reports the result from verifying the method.
 		private void ReportVerifiedMethod (MethodDefinition pointer, bool safe)
 		{
 			if (!safe) {
@@ -437,10 +423,8 @@ namespace Gendarme.Rules.Interoperability {
 			return -1;
 		}
 		
-		/// <summary>
-		/// Return the index of the load opcode.
-		/// This could probably go into InstructionRocks.
-		/// </summary>
+		// Return the index of the load opcode.
+		// This could probably go into InstructionRocks.
 		public static int GetLoadIndex (this Instruction ins)
 		{
 			switch (ins.OpCode.Code) {
@@ -458,10 +442,8 @@ namespace Gendarme.Rules.Interoperability {
 			}
 		}
 		
-		/// <summary>
-		/// Return the index of the store opcode.
-		/// This could probably go into InstructionRocks.
-		/// </summary>
+		// Return the index of the store opcode.
+		// This could probably go into InstructionRocks.
 		public static int GetStoreIndex (this Instruction ins)
 		{
 			switch (ins.OpCode.Code) {
diff --git a/gendarme/rules/Gendarme.Rules.Naming/UsePreferredTermsRule.cs b/gendarme/rules/Gendarme.Rules.Naming/UsePreferredTermsRule.cs
index adfb6905..0bbb457b 100644
--- a/gendarme/rules/Gendarme.Rules.Naming/UsePreferredTermsRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Naming/UsePreferredTermsRule.cs
@@ -127,12 +127,10 @@ namespace Gendarme.Rules.Naming {
 				{ "Writeable", "Writable" }
 			};
 		
-		/// <summary>
-		/// Reports a defect when 'name' contains a non-recommended term.
-		/// </summary>
-		/// <param name="identifier">Metadata token for 'name' or null if it is a namespace.</param>
-		/// <param name="name">Name to check.</param>
-		/// <param name="severity">Severity for the defect to be reported (if any).</param>
+		// Reports a defect when 'name' contains a non-recommended term.
+		// * identifier: Metadata token for 'name' or null if it is a namespace.
+		// * name: Name to check.
+		// * severity: Severity for the defect to be reported (if any).
 		private void CheckIdentifier (IMetadataTokenProvider identifier, string name, Severity severity)
 		{
 			// scan for any obsolete terms
diff --git a/gendarme/rules/Gendarme.Rules.Performance/ReviewLinqMethodRule.cs b/gendarme/rules/Gendarme.Rules.Performance/ReviewLinqMethodRule.cs
index 068a9c37..62bfc172 100644
--- a/gendarme/rules/Gendarme.Rules.Performance/ReviewLinqMethodRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Performance/ReviewLinqMethodRule.cs
@@ -43,7 +43,7 @@ namespace Gendarme.Rules.Performance {
 	/// Linq extension methods operate on sequences of values so they generally
 	/// have linear time complexity. However you may be able to achieve better
 	/// than linear time performance if you use a less general method or take
-	/// advantage of a method provided by an Sytem.Collections.Generic.IEnumerable&lt;T&gt; 
+	/// advantage of a method provided by an <c>Sytem.Collections.Generic.IEnumerable&lt;T&gt;</c> 
 	/// subclass.
 	/// </summary>
 	/// <example>
@@ -54,9 +54,8 @@ namespace Gendarme.Rules.Performance {
 	/// 	// Count () is O(n)
 	/// 	if (sequence.Count () &gt; 0) {
 	/// 		return sequence.First ();
-	/// 	} else {
-	/// 		return missing;
 	/// 	}
+	/// 	return missing;
 	/// }
 	/// 
 	/// public void Append (List&lt;string&gt; lines, string line)
@@ -76,9 +75,8 @@ namespace Gendarme.Rules.Performance {
 	/// 	// We don't need an exact count so we can use the O(1) Any () method.
 	/// 	if (sequence.Any ()) {
 	/// 		return sequence.First ();
-	/// 	} else {
-	/// 		return missing;
 	/// 	}
+	/// 	return missing;
 	/// }
 	/// 
 	/// public void Append (List&lt;string&gt; lines, string line)
@@ -91,6 +89,7 @@ namespace Gendarme.Rules.Performance {
 	/// }
 	/// </code>
 	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.6</remarks>
 
 	[Problem ("A linq extension method with linear time complexity is used, but a more efficient method is available.")]
 	[Solution ("Use the more efficient method.")]
diff --git a/gendarme/rules/Gendarme.Rules.Portability/MonoCompatibilityReviewRule.cs b/gendarme/rules/Gendarme.Rules.Portability/MonoCompatibilityReviewRule.cs
index 7d9a4867..3eebeec9 100644
--- a/gendarme/rules/Gendarme.Rules.Portability/MonoCompatibilityReviewRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Portability/MonoCompatibilityReviewRule.cs
@@ -54,13 +54,12 @@ namespace Gendarme.Rules.Portability {
 	/// or <c>C:\Documents and Settings\{username}\Local Settings\Application Data\Gendarme</c> 
 	/// (on Windows) and checking for calls to the methods therein. The rule will work without 
 	/// MoMA but if it does fire it may be useful to download and run MoMA.
-	/// </summary>
-	/// <remarks>
+	///
 	/// By default the rule will use the latest local version available. This can be overriden to use a 
 	/// specific, local, version if you want to review compatibility against a specific Mono version.
 	/// You can also manually remove them, now and then, to ensure you are using the latest version.
 	/// Also upgrading Gendarme will try to download a newer version of the definitions files.
-	/// </remarks>
+	/// </summary>
 
 	[Problem ("The method is either missing or partially implemented on Mono.")]
 	[Solution ("Review and test the code to ensure that it works properly on Mono. Also delete the definitions.zip to ensure that the latest version is downloaded.")]
diff --git a/gendarme/rules/Gendarme.Rules.Serialization/MarkEnumerationsAsSerializableRule.cs b/gendarme/rules/Gendarme.Rules.Serialization/MarkEnumerationsAsSerializableRule.cs
index c3526087..d959200e 100644
--- a/gendarme/rules/Gendarme.Rules.Serialization/MarkEnumerationsAsSerializableRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Serialization/MarkEnumerationsAsSerializableRule.cs
@@ -32,6 +32,32 @@ using Gendarme.Framework;
 
 namespace Gendarme.Rules.Serialization {
 
+	/// <summary>
+	/// This rule warns when it founds an <c>enum</c> that is not decorated with
+	/// a <c>[Serializable]</c> attribute. Enums, even without the attribute,
+	/// are always serializable. Marking them as such makes the source code more readable.
+	/// </summary>
+	/// <example>
+	/// Bad example:
+	/// <code>
+	/// public enum Colors {
+	///	Black,
+	///	White
+	/// }
+	/// </code>
+	/// </example>
+	/// <example>
+	/// Good example:
+	/// <code>
+	/// [Serializable]
+	/// public enum Colors {
+	///	Black,
+	///	White
+	/// }
+	/// </code>
+	/// </example>
+	/// <remarks>This rule is available since Gendarme 2.2</remarks>
+
 	[Problem ("An enumeration, even if not decorated with [Serializable], is always serializable.")]
 	[Solution ("For better source code readability always decorate enumerations with [Serializable].")]
 	public class MarkEnumerationsAsSerializableRule : Rule, ITypeRule {
diff --git a/gendarme/rules/Gendarme.Rules.Smells/AvoidSwitchStatementsRule.cs b/gendarme/rules/Gendarme.Rules.Smells/AvoidSwitchStatementsRule.cs
index 7bc097c6..fbd51890 100644
--- a/gendarme/rules/Gendarme.Rules.Smells/AvoidSwitchStatementsRule.cs
+++ b/gendarme/rules/Gendarme.Rules.Smells/AvoidSwitchStatementsRule.cs
@@ -63,16 +63,19 @@ namespace Gendarme.Rules.Smells {
 	/// int balance = 0;
 	/// foreach (Movie movie in movies) {
 	/// 	switch (movie.GetTypeCode ()) {
-	/// 	case MovieType.OldMovie:
-	/// 		balance += movie.DaysRented * movie.Price / 2;
-	/// 		break
-	/// 	case MovieType.ChildMovie:
-	/// 		//its an special bargain !!
-	/// 		balance += movie.Price;
-	/// 		break;
-	/// 	case MovieType.NewMovie:
-	/// 		balance += (movie.DaysRented + 1) * movie.Price;
-	/// 		break:
+	///	 	case MovieType.OldMovie: {
+	/// 			balance += movie.DaysRented * movie.Price / 2;
+	/// 			break;
+	///	 	}
+	/// 		case MovieType.ChildMovie: {
+	///	 		//its an special bargain !!
+	/// 			balance += movie.Price;
+	/// 			break;
+	///		}
+	///		case MovieType.NewMovie: {
+	///			balance += (movie.DaysRented + 1) * movie.Price;
+	///			break:
+	///		}
 	/// 	}
 	/// }
 	/// </code>
@@ -84,24 +87,28 @@ namespace Gendarme.Rules.Smells {
 	///	abstract int GetPrice ();
 	/// }
 	/// class OldMovie : Movie {
-	///	public override int GetPrice () {
+	///	public override int GetPrice ()
+	///	{
 	///		return DaysRented * Price / 2;
 	///	}
 	/// }
 	/// class ChildMovie : Movie {
-	///	public override int GetPrice () {
+	///	public override int GetPrice ()
+	///	{
 	///		return movie.Price;
 	///	}
 	/// }
 	/// class NewMovie : Movie {
-	///	public override int GetPrice () {
+	///	public override int GetPrice ()
+	///	{
 	///		return (DaysRented + 1) * Price;
 	///	}
 	/// }
 	///
 	/// int balance = 0;
-	/// foreach (Movie movie in movies)  
+	/// foreach (Movie movie in movies) {
 	/// 	balance += movie.GetPrice ()
+	/// }
 	/// </code>
 	/// </example>
 	/// <remarks>This rule is available since Gendarme 2.4</remarks>