Update user types documentation

Remove reference to a suppressed user type (INullableUserType), remove
obsolete documentation about mutability, cacheability and xml mode,
obsolete an unused interface.

Author: fredericDelaporte

doc/reference/modules/basic_mapping.xml

@@ -3982,12 +3982,11 @@
             </para>
 
             <para>
-                The <literal>ICompositeUserType</literal>, <literal>IEnhancedUserType</literal>,
-                <literal>INullableUserType</literal>, <literal>IUserCollectionType</literal>,
-                and <literal>IUserVersionType</literal> interfaces provide support for more specialized
-                uses.
+                The <literal>IEnhancedUserType</literal>, <literal>IUserVersionType</literal>,
+                and <literal>IUserCollectionType</literal> interfaces provide support for more specialized
+                uses. The later is to be used with collections, see <xref linkend="collections-persistent" />.
             </para>
-            
+
             <para>
                 You may even supply parameters to an <literal>IUserType</literal> in the mapping file. To
                 do this, your <literal>IUserType</literal> must implement the

src/NHibernate/UserTypes/ICompositeUserType.cs

@@ -9,19 +9,22 @@ namespace NHibernate.UserTypes
 	/// A UserType that may be dereferenced in a query.
 	/// This interface allows a custom type to define "properties".
 	/// These need not necessarily correspond to physical .NET style properties.
-	///
-	/// A ICompositeUserType may be used in almost every way
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// An <c>ICompositeUserType</c> may be used in almost every way
 	/// that a component may be used. It may even contain many-to-one
 	/// associations.
-	///
-	/// Implementors must be immutable and must declare a public
-	/// default constructor.
-	///
-	/// Unlike UserType, cacheability does not depend upon
-	/// serializability. Instead, Assemble() and
-	/// Disassemble() provide conversion to/from a cacheable
+	/// </para>
+	/// <para>
+	/// Implementors must declare a public default constructor.
+	/// </para>
+	/// <para>
+	/// For ensuring cacheability, <see cref="Assemble" /> and
+	/// <see cref="Disassemble" /> must provide conversion to/from a cacheable
 	/// representation.
-	/// </summary>
+	/// </para>
+	/// </remarks>
 	public interface ICompositeUserType
 	{
 		/// <summary>
@@ -135,4 +138,4 @@ public interface ICompositeUserType
 		/// </summary>
 		object Replace(object original, object target, ISessionImplementor session, object owner);
 	}
-}
+}

src/NHibernate/UserTypes/IEnhancedUserType.cs

@@ -4,7 +4,7 @@ namespace NHibernate.UserTypes
 {
 	/// <summary>
 	/// A custom type that may function as an identifier or discriminator
-	/// type, or may be marshalled to and from an XML document.
+	/// type.
 	/// </summary>
 	public interface IEnhancedUserType : IUserType
 	{

src/NHibernate/UserTypes/ILoggableUserType.cs

@@ -1,3 +1,4 @@
+using System;
 using NHibernate.Engine;
 
 namespace NHibernate.UserTypes
@@ -6,6 +7,8 @@ namespace NHibernate.UserTypes
 	/// Marker interface for user types which want to perform custom
 	/// logging of their corresponding values 
 	/// </summary>
+	// Since 5.2
+	[Obsolete("This interface has no usage and will be removed in a future version")]
 	public interface ILoggableUserType
 	{
 		/// <summary> Generate a loggable string representation of the collection (value). </summary>

src/NHibernate/UserTypes/IUserType.cs

@@ -10,19 +10,23 @@ namespace NHibernate.UserTypes
 	/// <remarks>
 	/// <para>
 	/// The interface abstracts user code from future changes to the <see cref="Type.IType"/> interface,
-	/// simplifies the implementation of custom types and hides certain "internal interfaces from
+	/// simplifies the implementation of custom types and hides certain "internal interfaces" from
 	/// user code.
 	/// </para>
 	/// <para>
-	/// Implementers must be immutable and must declare a public default constructor.
+	/// Implementers must declare a public default constructor.
 	/// </para>
 	/// <para>
-	/// The actual class mapped by a <c>IUserType</c> may be just about anything. However, if it is to
-	/// be cacheble by a persistent cache, it must be serializable.
+	/// The actual class mapped by a <c>IUserType</c> may be just about anything.
+	/// </para>
+	/// <para>
+	/// For ensuring cacheability, <see cref="Assemble" /> and
+	/// <see cref="Disassemble" /> must provide conversion to/from a cacheable
+	/// representation.
 	/// </para>
 	/// <para>
 	/// Alternatively, custom types could implement <see cref="Type.IType"/> directly or extend one of the
-	/// abstract classes in <c>NHibernate.Type</c>. This approach risks future incompatible changes
+	/// abstract classes in <c>NHibernate.Type</c>. This approach risks more future incompatible changes
 	/// to classes or interfaces in the package.
 	/// </para>
 	/// </remarks>