Document IsDirty side effects.

 * Fixes #1449.

Author: fredericDelaporte

doc/reference/modules/manipulating_data.xml

@@ -820,7 +820,7 @@ sess.Lock(pk, LockMode.Upgrade);]]></programlisting>
         </orderedlist>
 
         <para>
-            (An exception is that objects using <literal>native</literal> ID generation are 
+            (An exception is that objects using <literal>identity</literal> ID generation are
             inserted when they are saved.)
         </para>
 
@@ -861,6 +861,37 @@ using (ITransaction tx = sess.BeginTransaction())
 
     </sect1>
 
+    <sect1 id="manipulatingdata-dirtiness">
+        <title>Checking dirtiness</title>
+
+        <para>
+            <literal>ISession.IsDirty()</literal> will return whether the session hold any pending
+            change to flush or not. Be cautious when using this method, its default implementation
+            may have the following effects:
+        </para>
+
+        <itemizedlist spacing="compact">
+            <listitem>
+                <para>
+                    Dirty checks all the loaded entities. NHibernate does not instrument the entities
+                    for being notified of changes done on loaded ones. Instead, it stores their
+                    initial state and compare them to it. If session has loaded a lot of entities,
+                    the dirty checking will have a significant impact.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Triggers pending cascade operations. This includes any pending <literal>Save</literal>
+                    of, by example, children added to a collection having the <literal>Save</literal>
+                    cascade enabled. Depending on the entities ID generators (see
+                    <xref linkend="mapping-declaration-id-generator"/>), this may trigger calls to the
+                    database, or even entity insertions if they are using the <literal>identity</literal>
+                    generator.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect1>
+
     <sect1 id="manipulatingdata-endingsession">
         <title>Ending a Session</title>
 

src/NHibernate/Async/ISession.cs

@@ -14,6 +14,8 @@
 using System.Linq;
 using System.Linq.Expressions;
 using NHibernate.Engine;
+using NHibernate.Event;
+using NHibernate.Event.Default;
 using NHibernate.Stat;
 using NHibernate.Type;
 
@@ -38,9 +40,25 @@ public partial interface ISession : IDisposable
 		/// <summary>
 		/// Does this <c>ISession</c> contain any changes which must be
 		/// synchronized with the database? Would any SQL be executed if
-		/// we flushed this session?
+		/// we flushed this session? May trigger save cascades, which could
+		/// cause themselves some SQL to be executed, especially if the
+		/// <c>identity</c> id generator is used.
 		/// </summary>
 		/// <param name="cancellationToken">A cancellation token that can be used to cancel the work</param>
+		/// <remarks>
+		/// <para>
+		/// The default implementation first checks if it contains saved or deleted entities to be flushed. If not, it
+		/// then delegate the check to its <see cref="IDirtyCheckEventListener" />, which by default is
+		/// <see cref="DefaultDirtyCheckEventListener" />.
+		/// </para>
+		/// <para>
+		/// <see cref="DefaultDirtyCheckEventListener" /> replicates all the beginning of the flush process, checking
+		/// dirtiness of entities loaded in the session and triggering their pending cascade operations in order to
+		/// detect new and removed children. This can have the side effect of performing the <see cref="Save(object)"/>
+		/// of children, causing their id to be generated. Depending on their id generator, this can trigger calls to
+		/// the database and even actually insert them if using an <c>identity</c> generator.
+		/// </para>
+		/// </remarks>
 		Task<bool> IsDirtyAsync(CancellationToken cancellationToken = default(CancellationToken));
 
 		/// <summary>

src/NHibernate/ISession.cs

@@ -4,6 +4,8 @@
 using System.Linq;
 using System.Linq.Expressions;
 using NHibernate.Engine;
+using NHibernate.Event;
+using NHibernate.Event.Default;
 using NHibernate.Stat;
 using NHibernate.Type;
 
@@ -179,8 +181,24 @@ public partial interface ISession : IDisposable
 		/// <summary>
 		/// Does this <c>ISession</c> contain any changes which must be
 		/// synchronized with the database? Would any SQL be executed if
-		/// we flushed this session?
+		/// we flushed this session? May trigger save cascades, which could
+		/// cause themselves some SQL to be executed, especially if the
+		/// <c>identity</c> id generator is used.
 		/// </summary>
+		/// <remarks>
+		/// <para>
+		/// The default implementation first checks if it contains saved or deleted entities to be flushed. If not, it
+		/// then delegate the check to its <see cref="IDirtyCheckEventListener" />, which by default is
+		/// <see cref="DefaultDirtyCheckEventListener" />.
+		/// </para>
+		/// <para>
+		/// <see cref="DefaultDirtyCheckEventListener" /> replicates all the beginning of the flush process, checking
+		/// dirtiness of entities loaded in the session and triggering their pending cascade operations in order to
+		/// detect new and removed children. This can have the side effect of performing the <see cref="Save(object)"/>
+		/// of children, causing their id to be generated. Depending on their id generator, this can trigger calls to
+		/// the database and even actually insert them if using an <c>identity</c> generator.
+		/// </para>
+		/// </remarks>
 		bool IsDirty();
 
 		/// <summary>