Document difference between .Insert()/.Update and .Generated.Insert()/.Update()

Closes #364

+semver:patch

Author: hazzik

src/FluentNHibernate/Conventions/Inspections/Generated.cs

@@ -2,9 +2,26 @@ namespace FluentNHibernate.Conventions.Inspections
 {
     public class Generated
     {
+        /// <summary>
+        /// Use the default value.
+        /// </summary>
         public static readonly Generated Unset = new Generated("");
+
+        /// <summary>
+        /// The property value as not generated within the database (default).
+        /// </summary>
         public static readonly Generated Never = new Generated("never");
+
+        /// <summary>
+        /// The property value as generated on INSERT, but is not regenerated on subsequent updates.
+        /// <para>NHibernate will immediately issues a SELECT after INSERT to retrieve the generated values.</para>
+        /// </summary>
         public static readonly Generated Insert = new Generated("insert");
+
+        /// <summary>
+        /// The property value as generated both on INSERT and on UPDATE.
+        /// <para>NHibernate will immediately issues a SELECT after INSERT or UPDATE to retrieve the generated values.</para>
+        /// </summary>
         public static readonly Generated Always = new Generated("always");
 
         private readonly string value;
@@ -16,7 +33,7 @@ private Generated(string value)
 
         public override bool Equals(object obj)
         {
-            if (obj is Generated) return Equals((Generated)obj);
+            if (obj is Generated) return Equals((Generated) obj);
 
             return base.Equals(obj);
         }

src/FluentNHibernate/Conventions/Instances/GeneratedInstance.cs

@@ -2,6 +2,7 @@
 
 namespace FluentNHibernate.Conventions.Instances
 {
+    /// <inheritdoc cref="IGeneratedInstance"/>
     public class GeneratedInstance : IGeneratedInstance
     {
         private readonly Action<string> setter;
@@ -11,16 +12,19 @@ public GeneratedInstance(Action<string> setter)
             this.setter = setter;
         }
 
+        /// <inheritdoc />
         public void Never()
         {
             setter("never");
         }
 
+        /// <inheritdoc />
         public void Insert()
         {
             setter("insert");
         }
 
+        /// <inheritdoc />
         public void Always()
         {
             setter("always");

src/FluentNHibernate/Conventions/Instances/IGeneratedInstance.cs

@@ -1,11 +1,27 @@
-using FluentNHibernate.Conventions.Inspections;
-
 namespace FluentNHibernate.Conventions.Instances
 {
+    /// <summary>
+    /// Instructs NHibernate to immediately issues a SELECT after INSERT or UPDATE to retrieve the generated values.
+    /// <para> See https://nhibernate.info/doc/nhibernate-reference/mapping.html#mapping-generated for more information. </para>
+    /// </summary>
+    /// <remarks> It is user's responsibility to specify how the columns are generated. </remarks>
     public interface IGeneratedInstance
     {
+        /// <summary>
+        /// Marks the property value as not generated within the database (default).
+        /// </summary>
         void Never();
+
+        /// <summary>
+        /// Marks the property value as generated on INSERT, but is not regenerated on subsequent UPDATEs.
+        /// <para>NHibernate will immediately issues a SELECT after INSERT to retrieve the generated values.</para>
+        /// </summary>
         void Insert();
+
+        /// <summary>
+        /// Marks the property value as generated both on INSERT and on UPDATE.
+        /// <para>NHibernate will immediately issues a SELECT after INSERT or UPDATE to retrieve the generated values.</para>
+        /// </summary>
         void Always();
     }
 }

src/FluentNHibernate/Conventions/Instances/IInsertInstance.cs

@@ -2,6 +2,9 @@ namespace FluentNHibernate.Conventions.Instances
 {
     public interface IInsertInstance
     {
+        /// <summary>
+        /// Specifies that the mapped columns should be included in or excluded from SQL INSERT statement.
+        /// </summary>
         void Insert();
     }
 }

src/FluentNHibernate/Conventions/Instances/IPropertyInstance.cs

@@ -30,6 +30,11 @@ public interface IPropertyInstance
         new void UniqueKey(string keyName);
         void Column(string columnName);
         new void Formula(string formula);
+        /// <summary>
+        /// Instructs NHibernate to immediately issues a SELECT after INSERT or UPDATE to retrieve the generated values.
+        /// <para> See https://nhibernate.info/doc/nhibernate-reference/mapping.html#mapping-generated for more information. </para>
+        /// </summary>
+        /// <remarks> It is user's responsibility to specify how the columns are generated. </remarks>
         new IGeneratedInstance Generated { get; }
         new void OptimisticLock();
         new void Length(int length);

src/FluentNHibernate/Conventions/Instances/IReadOnlyInstance.cs

@@ -2,6 +2,7 @@ namespace FluentNHibernate.Conventions.Instances
 {
     public interface IReadOnlyInstance
     {
+        /// <summary> Shortcut for setting <c>.Not.Insert().Not.Update()</c>. </summary>
         void ReadOnly();
     }
 }

src/FluentNHibernate/Conventions/Instances/IUpdateInstance.cs

@@ -2,6 +2,7 @@ namespace FluentNHibernate.Conventions.Instances
 {
     public interface IUpdateInstance
     {
+        /// Specifies that the mapped columns should be included or excluded in SQL UPDATE statement.
         void Update();
     }
 }

src/FluentNHibernate/Conventions/Instances/IVersionInstance.cs

@@ -7,6 +7,11 @@ namespace FluentNHibernate.Conventions.Instances
     public interface IVersionInstance : IVersionInspector
     {
         new IAccessInstance Access { get; }
+        /// <summary>
+        /// Instructs NHibernate to immediately issues a SELECT after INSERT or UPDATE to retrieve the generated values.
+        /// <para> See https://nhibernate.info/doc/nhibernate-reference/mapping.html#mapping-generated for more information. </para>
+        /// </summary>
+        /// <remarks> It is user's responsibility to specify how the columns are generated. </remarks>
         new IGeneratedInstance Generated { get; }
         [DebuggerBrowsable(DebuggerBrowsableState.Never)]
         IVersionInstance Not { get; }

src/FluentNHibernate/Conventions/Instances/PropertyInstance.cs

@@ -19,18 +19,21 @@ public PropertyInstance(PropertyMapping mapping)
             this.mapping = mapping;
         }
 
+        /// <inheritdoc />
         public new void Insert()
         {
             mapping.Set(x => x.Insert, layer, nextBool);
             nextBool = true;
         }
 
+        /// <inheritdoc />
         public new void Update()
         {
             mapping.Set(x => x.Update, layer, nextBool);
             nextBool = true;
         }
 
+        /// <inheritdoc />
         public new void ReadOnly()
         {
             mapping.Set(x => x.Insert, layer, !nextBool);
@@ -159,6 +162,7 @@ public void Column(string columnName)
             mapping.MakeColumnsEmpty(Layer.UserSupplied);
         }
 
+        /// <inheritdoc />
         public new IGeneratedInstance Generated
         {
             get { return new GeneratedInstance(value => mapping.Set(x => x.Generated, layer, value)); }

src/FluentNHibernate/Conventions/Instances/VersionInstance.cs

@@ -23,6 +23,7 @@ public VersionInstance(VersionMapping mapping)
             get { return new AccessInstance(value => mapping.Set(x => x.Access, layer, value)); }
         }
 
+        /// <inheritdoc />
         public new IGeneratedInstance Generated
         {
             get { return new GeneratedInstance(value => mapping.Set(x => x.Generated, layer, value)); }