improve some language in Session javadoc

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -241,6 +241,8 @@ When a transaction rolls back, Hibernate makes no attempt to roll back the state
 After a transaction rollback, the persistence context must be discarded, and the state of its entities must be assumed inconsistent with the state held by the database.
 ====
 
+The interface link:{doc-javadoc-url}org/hibernate/Transaction.html[`Transaction`] extends `EntityTransaction` with some additional operations, including the ability to register transaction completion callbacks.
+
 [[persistence-operations]]
 === Operations on the persistence context
 
@@ -743,13 +745,13 @@ session.getTransaction().commit();
 | `ALWAYS` | | Flush before transaction commit, and before execution of every query
 |===
 
-A second way to reduce the cost of flushing is to load entities in _read-only_ mode:
+A second way to reduce the cost of flushing is to load entities in link:{doc-javadoc-url}org/hibernate/Session.html#setDefaultReadOnly(boolean)[_read-only_ mode]:
 
 - `Session.setDefaultReadOnly(true)` specifies that all entities loaded by a given session should be loaded in read-only mode by default,
 - `SelectionQuery.setReadOnly(true)` specifies that every entity returned by a given query should be loaded in read-only mode, and
 - `Session.setReadOnly(Object, true)` specifies that a given entity already loaded by the session should be switched to read-only mode.
 
-Hibernate's `ReadOnlyMode` is a custom `FindOption`:
+Hibernate's link:{doc-javadoc-url}org/hibernate/ReadOnlyMode.html[`ReadOnlyMode`] is a custom `FindOption`:
 
 [source,java]
 ----

hibernate-core/src/main/java/org/hibernate/ReadOnlyMode.java

@@ -22,9 +22,10 @@ public enum ReadOnlyMode implements FindOption {
 	/**
 	 * Specifies that an entity should be loaded in read-only mode.
 	 * <p>
-	 * Read-only entities are not dirty-checked and snapshots of
+	 * Read-only entities are not dirty-checked, and snapshots of
 	 * persistent state are not maintained. Read-only entities can
-	 * be modified, but changes are not persisted.
+	 * be modified, but a modification to a field of a read-only
+	 * entity is not made persistent
 	 */
 	READ_ONLY,
 	/**

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -417,23 +417,27 @@ public interface Session extends SharedSessionContract, EntityManager {
 
 	/**
 	 * Change the default for entities and proxies loaded into this session
-	 * from modifiable to read-only mode, or from modifiable to read-only mode.
+	 * from modifiable to read-only mode, or from read-only to modifiable mode.
 	 * <p>
-	 * Read-only entities are not dirty-checked and snapshots of persistent
-	 * state are not maintained. Read-only entities can be modified, but
-	 * changes are not persisted.
+	 * Read-only entities are not dirty-checked, and snapshots of persistent
+	 * state are not maintained. Read-only entities can be modified, but a
+	 * modification to a field of a read-only entity is not made persistent.
 	 * <p>
 	 * When a proxy is initialized, the loaded entity will have the same
-	 * read-only/modifiable setting as the uninitialized proxy has,
-	 * regardless of the session's current setting.
+	 * read-only/modifiable setting as the uninitialized proxy, regardless of
+	 * the {@linkplain #isDefaultReadOnly current default read-only mode}
+	 * of the session.
 	 * <p>
 	 * To change the read-only/modifiable setting for a particular entity
-	 * or proxy that already belongs to this session use
+	 * or proxy that already belongs to this session, use
 	 * {@link #setReadOnly(Object, boolean)}.
 	 * <p>
-	 * To override this session's read-only/modifiable setting for all
-	 * entities and proxies loaded by a certain {@code Query} use
+	 * To override the default read-only mode of the current session for
+	 * all entities and proxies returned by a given {@code Query}, use
 	 * {@link Query#setReadOnly(boolean)}.
+	 * <p>
+	 * Every instance of an {@linkplain org.hibernate.annotations.Immutable
+	 * immutable} entity is loaded in read-only mode.
 	 *
 	 * @see #setReadOnly(Object,boolean)
 	 * @see Query#setReadOnly(boolean)
@@ -1287,7 +1291,8 @@ public interface Session extends SharedSessionContract, EntityManager {
 	/**
 	 * Set an unmodified persistent object to read-only mode, or a read-only
 	 * object to modifiable mode. In read-only mode, no snapshot is maintained,
-	 * the instance is never dirty checked, and changes are not persisted.
+	 * the instance is never dirty-checked, and mutations to the fields of the
+	 * entity are not made persistent.
 	 * <p>
 	 * If the entity or proxy already has the specified read-only/modifiable
 	 * setting, then this method does nothing.
@@ -1296,17 +1301,24 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * and proxies that are loaded into the session use
 	 * {@link #setDefaultReadOnly(boolean)}.
 	 * <p>
-	 * To override this session's read-only/modifiable setting for entities
-	 * and proxies loaded by a {@code Query} use
-	 * {@link Query#setReadOnly(boolean)}
+	 * To override the default read-only mode of the current session for
+	 * all entities and proxies returned by a given {@code Query}, use
+	 * {@link Query#setReadOnly(boolean)}.
+	 * <p>
+	 * Every instance of an {@linkplain org.hibernate.annotations.Immutable
+	 * immutable} entity is loaded in read-only mode. An immutable entity may
+	 * not be set to modifiable.
 	 *
 	 * @see #setDefaultReadOnly(boolean)
 	 * @see Query#setReadOnly(boolean)
 	 * @see IdentifierLoadAccess#withReadOnly(boolean)
+	 * @see org.hibernate.annotations.Immutable
 	 *
 	 * @param entityOrProxy an entity or proxy
 	 * @param readOnly {@code true} if the entity or proxy should be made read-only;
 	 *				   {@code false} if the entity or proxy should be made modifiable
+	 *
+	 * @throws IllegalStateException if an immutable entity is set to modifiable
 	 */
 	void setReadOnly(Object entityOrProxy, boolean readOnly);