Fixing some of the xmldoc problems.

SVN: trunk@950

Author: Mike Doerfler

src/NHibernate/Collection/PersistentCollection.cs

@@ -13,25 +13,24 @@ namespace NHibernate.Collection
 	/// automatically deleted when unreferenced and automatically become
 	/// persistent when held by a persistent object. Collections can be
 	/// passed between different objects (change "roles") and this might
-	/// cause their elements to move from one database table to another.<br>
-	/// <br>
+	/// cause their elements to move from one database table to another.
+	/// <br /><br />
 	/// Hibernate "wraps" a java collection in an instance of
 	/// PersistentCollection. This mechanism is designed to support
 	/// tracking of changes to the collection's persistent state and
 	/// lazy instantiation of collection elements. The downside is that
 	/// only certain abstract collection types are supported and any
-	/// extra semantics are lost<br>
-	/// <br>
-	/// Applications should <em>never</em> use classes in this package 
-	/// directly, unless extending the "framework" here.<br>
-	/// <br>
-	/// Changes to <em>structure</em> of the collection are recorded by the
+	/// extra semantics are lost.
+	/// <br /><br />
+	/// Applications should <b>never</b> use classes in this package 
+	/// directly, unless extending the "framework" here.
+	/// <br /><br />
+	/// Changes to <b>structure</b> of the collection are recorded by the
 	/// collection calling back to the session. Changes to mutable
 	/// elements (ie. composite elements) are discovered by cloning their
 	/// state when the collection is initialized and comparing at flush
 	/// time.
 	/// 
-	/// @author Gavin King
 	/// </summary>
 	[Serializable]
 	public abstract class PersistentCollection 

src/NHibernate/Collection/Set.cs

@@ -31,7 +31,7 @@ public class Set : PersistentCollection, IDictionary {
 		[NonSerialized] protected IList tempIdentifierList;
 
 		/// <summary>
-		/// Returns a Hashtable where the Key & the Value are both a Copy of the
+		/// Returns a Hashtable where the Key &amp; the Value are both a Copy of the
 		/// same object.
 		/// <see cref="PersistentCollection.Snapshot"/>
 		/// </summary>

src/NHibernate/Engine/IPreparer.cs

@@ -22,7 +22,7 @@ public interface IPreparer
 		/// Prepares the IDbCommand for the IDbConnection
 		/// 
 		/// DESIGNTHOUGHT: This is a bit of a false statement now - in order for ADO.NET to Prepare a command the
-		/// Size & Precision of the Parameter HAVE to be set.  The current NHibernate codebase does
+		/// Size & Precision of the Parameter HAVE to be set.  The current NHibernate codebase does
 		/// not do this.  I think to IType we can add a method int[] Size() and int[] Precision and
 		/// update each Type accordingly.  The only bad part about that is that for var length Parameters
 		/// we will probably be setting the length to the max size and precision - I don't know if that would 

src/NHibernate/Mapping/Property.cs

@@ -26,16 +26,25 @@ public IType Type
 			get { return propertyValue.Type; }
 		}
 
+		/// <summary>
+		/// Gets the number of columns this property uses in the db.
+		/// </summary>
 		public int ColumnSpan 
 		{
 			get { return propertyValue.ColumnSpan; }
 		}
 
+		/// <summary>
+		/// Gets an <see cref="ICollection"/> of <see cref="Column"/>s.
+		/// </summary>
 		public ICollection ColumnCollection 
 		{
 			get { return propertyValue.ColumnCollection; }
 		}
 
+		/// <summary>
+		/// Gets or Sets the name of the Property in the class.
+		/// </summary>
 		public string Name 
 		{
 			get { return name; }

src/NHibernate/Mapping/RootClass.cs

@@ -4,6 +4,84 @@
 
 namespace NHibernate.Mapping 
 {	
+	/// <summary>
+	/// Declaration of a System.Type by using the <c>&lt;class&gt;</c> element.
+	/// </summary>
+	/// <remarks>
+	/// <p>The <c>&lt;class&gt;</c> element has the following attributes available:</p>
+	/// <list type="table">
+	///		<listheader>
+	///			<term>Attribute</term>
+	///			<description>Possible Values</description>
+	///		</listheader>
+	///		<item>
+	///			<term>name</term>
+	///			<description>The fully qualified TypeName so it can be loaded by Reflection</description>
+	///		</item>
+	///		<item>
+	///			<term>table</term>
+	///			<description>The name of its database table.</description>
+	///		</item>
+	///		<item>
+	///			<term>discriminator-value</term>
+	///			<description>
+	///				(optional - defaults to the FullClassName)  A value that distinguishes individual
+	///				subclasses, used for polymorphic behavior.
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>mutable</term>
+	///			<description>
+	///				(optional - defaults to <c>true</c>)  Specifies that instances of the class
+	///				are (not) mutable.
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>schema</term>
+	///			<description>(optional)  Override the schema name specified by the root <c>&lt;hibernate-mapping&gt;</c> element.</description>
+	///		</item>
+	///		<item>
+	///			<term>proxy</term>
+	///			<description>
+	///				(optional) Specifies an interface to use for lazy initializing proxies.  
+	///				You may specify the name of the class itself. 
+	///				(TODO: update once Proxies are implemented)
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>dynamic-update</term>
+	///			<description>
+	///				(optional - defaults to <c>false</c>) Specifies the <c>UPDATE</c> SQL should 
+	///				be generated at runtime and contain only those columns whose values have changed.
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>dynamic-insert</term>
+	///			<description>
+	///				(optional - defaults to <c>false</c>)  Specifies the <c>INSERT</c> SQL should 
+	///				be generated at runtime and contain only those columns whose values are not null.
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>polymorphism</term>
+	///			<description>
+	///				(optional, defaults to <c>implicit</c>)  Determines whether implicit or explicit
+	///				query polymorphism is used.	
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>where</term>
+	///			<description>
+	///				(optional) Specify an arbitrary SQL <c>WHERE</c> condition to be used 
+	///				when retrieving objects of this class.
+	///			</description>
+	///		</item>
+	///		<item>
+	///			<term>persister</term>
+	///			<description>(optional)  Specifies a custom <see cref="Persister.IClassPersister"/>.</description>
+	///		</item>
+	/// </list>
+	/// </remarks>
 	public class RootClass : PersistentClass 
 	{
 		private static readonly log4net.ILog log = log4net.LogManager.GetLogger(typeof(RootClass));
@@ -110,12 +188,53 @@ public override bool IsExplicitPolymorphism
 			set { explicitPolymorphism = value; }
 		}
 
+		/// <summary>
+		/// Gets or Sets the <see cref="Property"/> to use as the Version Property
+		/// </summary>
+		/// <value>The <see cref="Property"/> to use for Versioning.</value>
+		/// <remarks>
+		/// <para>
+		/// The &;tlversion&gt; element is optional and indicates that the table contains versioned data. 
+		/// This is particularly useful if you plan to use long transactions (see below). 
+		/// </para>
+		/// <para>
+		/// <list type="table">
+		///		<listheader>
+		///			<term>Attribute</term>
+		///			<description>Possible Values</description>
+		///		</listheader>
+		///		<item>
+		///			<term>column</term>
+		///			<description>
+		///				The name of the <c>column</c> holding the version number.  
+		///				Defaults to the Property name.
+		///			</description>
+		///		</item>
+		///		<item>
+		///			<term>name</term>
+		///			<description>The name of the Property in the Persistent Class.</description>
+		///		</item>
+		///		<item>
+		///			<term>type</term>
+		///			<description>
+		///				The <see cref="Type.IType"/> of the Property.  Defaults to an <see cref="Type.Int32Type"/>.  It 
+		///				be any <see cref="Type.IVersionType"/>.   
+		///			</description>
+		///		</item>
+		///	</list>
+		/// </para>
+		/// </remarks>
 		public override Property Version 
 		{
 			get { return version; }
 			set { version = value; }
 		}
 
+		/// <summary>
+		/// Gets a value indicating if the <see cref="PersistentClass" /> is versioned
+		/// by NHibernate.
+		/// </summary>
+		/// <value><c>true</c> if there is a version property.</value>
 		public override bool IsVersioned 
 		{
 			get { return version != null; }

src/NHibernate/Property/FieldAccessor.cs

@@ -66,7 +66,7 @@ internal static FieldInfo GetField(System.Type clazz, string fieldName)
 		/// <param name="propertyName">The name of the Property.</param>
 		/// <returns>The name of the Field.</returns>
 		/// <remarks>
-		/// This uses the convention that a Property named <c>Id</c> will have a field </c>id</c>
+		/// This uses the convention that a Property named <c>Id</c> will have a field <c>id</c>
 		/// </remarks>
 		private string GetFieldName(string propertyName) 
 		{

src/NHibernate/Property/PropertyAccessorFactory.cs

@@ -30,12 +30,12 @@ private PropertyAccessorFactory()
 		/// <param name="type"></param>
 		/// <returns></returns>
 		/// <remarks>
-		/// <p>
+		/// <para>
 		/// The built in ways of accessing the values of Properties in your domain class are:
-		/// </p>
+		/// </para>
 		/// <list type="table">
 		///		<listheader>
-		///			<term>access method</term>
+		///			<term>Access Method</term>
 		///			<description>How NHibernate accesses the Mapped Class.</description>
 		///		</listheader>
 		///		<item>
@@ -51,7 +51,7 @@ private PropertyAccessorFactory()
 		///				The <c>name</c> attribute is the name of the field.  If you have any Properties
 		///				in the Mapped Class those will be bypassed and NHibernate will go straight to the
 		///				field.  This is a good option if your setters have business rules attached to them
-		///				or if you don't want to expose a field through a Getter & Setter.
+		///				or if you don't want to expose a field through a Getter &amp; Setter.
 		///			</description>
 		///		</item>
 		///		<item>
@@ -72,11 +72,15 @@ private PropertyAccessorFactory()
 		///			</description>
 		///		</item>
 		///	</list>
-		///	<p>
+		///	<para>
 		///	In order for the <c>nosetter</c> to know the name of the field to access NHibernate needs to know
 		///	what the naming strategy is.  The following naming strategies are built into NHibernate:
-		///	</p>
+		///	</para>
 		///	<list type="table">
+		///		<listheader>
+		///			<term>Naming Strategy</term>
+		///			<description>How NHibernate converts the value of the <c>name</c> attribute to a field name.</description>
+		///		</listheader>
 		///		<item>
 		///			<term>camelcase</term>
 		///			<description>

src/NHibernate/SqlCommand/SqlBaseBuilder.cs

@@ -44,7 +44,7 @@ protected SqlString ToWhereString(string tableAlias, string[] columnNames, objec
 		/// </summary>
 		/// <param name="columnNames">The names of the Columns to Add to the WhereFragment</param>
 		/// <param name="columnValues">The Values for the Columns in the WhereFragment</param>
-		/// <param name="op">The operator to use between the names & values.  For example " = " or "!="</param>
+		/// <param name="op">The operator to use between the names &amp; values.  For example " = " or "!="</param>
 		/// <returns>A SqlString that contains the WhereFragment</returns>
 		protected SqlString ToWhereString(string[] columnNames, object[] columnValues, string op) {
 			return ToWhereString(null, columnNames, columnValues, op);
@@ -56,7 +56,7 @@ protected SqlString ToWhereString(string[] columnNames, object[] columnValues, s
 		/// <param name="tableAlias">The Alias for the Table.</param>
 		/// <param name="columnNames">The names of the Columns to Add to the WhereFragment</param>
 		/// <param name="columnValues">The Values for the Columns in the WhereFragment</param>
-		/// <param name="op">The operator to use between the names & values.  For example " = " or "!="</param>
+		/// <param name="op">The operator to use between the names &amp; values.  For example " = " or "!="</param>
 		/// <returns>A SqlString that contains the WhereFragment</returns>
 		protected SqlString ToWhereString(string tableAlias, string[] columnNames, object[] columnValues, string op) {
 			SqlStringBuilder sqlBuilder = new SqlStringBuilder((columnNames.Length * 2) + 5);

src/NHibernate/Type/DateTimeType.cs

@@ -7,7 +7,7 @@ namespace NHibernate.Type
 {
 
 	/// <summary>
-	/// Maps a System.DateTime Property to a column that stores date & time down to 
+	/// Maps a System.DateTime Property to a column that stores date &amp; time down to 
 	/// the accuracy of a second.
 	/// </summary>
 	/// <remarks>
@@ -91,6 +91,7 @@ public override object DeepCopyNotNull(object value)
 			return (DateTime)value;
 		}
 
+
 		public override bool HasNiceEquals 
 		{
 			get { return true; }

src/NHibernate/Util/IdentityMap.cs

@@ -7,23 +7,24 @@ namespace NHibernate.Util
 {
 
 	/// <summary>
-	/// An <c>IDictionary</c> where keys are compared by object identity, rather than <c>equals</c>.
+	/// An <see cref="IDictionary" /> where keys are compared by object identity, rather than <c>equals</c>.
 	/// 
 	/// All external users of this class need to have no knowledge of the IdentityKey - it is all
 	/// hidden by this class.
 	/// </summary>
 	/// <remarks>
+	/// <para>
 	/// Do NOT use a System.Value type as the key for this Hashtable - only classes.  See
-	/// the google thread 
-	/// http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&threadm=bds2rm%24ruc%241%40charly.heeg.de&rnum=1&prev=/groups%3Fhl%3Den%26lr%3D%26ie%3DUTF-8%26oe%3DUTF-8%26q%3DSystem.Runtime.CompilerServices.RuntimeHelpers.GetHashCode%26sa%3DN%26tab%3Dwg
+	/// the <a href="http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&threadm=bds2rm%24ruc%241%40charly.heeg.de&rnum=1&prev=/groups%3Fhl%3Den%26lr%3D%26ie%3DUTF-8%26oe%3DUTF-8%26q%3DSystem.Runtime.CompilerServices.RuntimeHelpers.GetHashCode%26sa%3DN%26tab%3Dwg">google thread</a>
 	/// about why using System.Value is a bad thing.
-	/// <p>
+	/// </para>
+	/// <para>
 	/// If I understand it correctly, the first call to get an object defined by a DateTime("2003-01-01")
 	/// would box the DateTime and return the identity key for the box.  If you were to get that Key and
 	/// unbox it into a DateTime struct, then the next time you passed it in as the Key the IdentityMap
 	/// would box it again (into a different box) and it would have a different IdentityKey - so you would
 	/// not get the same value for the same DateTime value. 
-	/// </p>
+	/// </para>
 	/// </remarks>
 	[Serializable]
 	public sealed class IdentityMap : IDictionary