improve some language in Session javadoc

Author: gavinking

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

@@ -417,22 +417,23 @@ 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)}.
 	 *
 	 * @see #setReadOnly(Object,boolean)
@@ -1287,7 +1288,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.