HHH-13165 - Don't use confusing "this" in the User Guide admonition b…

…locks

documentation/src/main/asciidoc/userguide/appendices/Legacy_Bootstrap.adoc

@@ -7,7 +7,8 @@ I like to think of `Configuration` as a big pot to which we add a bunch of stuff
 
 [NOTE]
 ====
-There are some significant draw backs to this approach which led to its deprecation and the development of the new approach, which is discussed in  <<chapters/bootstrap/Bootstrap.adoc#bootstrap-native,Native Bootstrapping>>.
+There are some significant drawbacks to the legacy bootstrapping mechanism which led to its deprecation and the development of the new approach, which is discussed in  <<chapters/bootstrap/Bootstrap.adoc#bootstrap-native,Native Bootstrapping>>.
+
 `Configuration` is semi-deprecated but still available for use, in a limited form that eliminates these drawbacks.
 "Under the covers", `Configuration` uses the new bootstrapping code, so the things available there as also available here in terms of auto-discovery.
 ====

documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc

@@ -267,7 +267,7 @@ The following example shows how to define custom SQL operations using annotation
 
 [NOTE]
 ====
-If you expect to call a store procedure, be sure to set the `callable` attribute to `true`, in annotations as well as in xml.
+If you expect to call a stored procedure, be sure to set the `callable` attribute to `true` in both annotation and XML-based mappings.
 ====
 
 To check that the execution happens correctly, Hibernate allows you to define one of those three strategies:

documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc

@@ -38,7 +38,7 @@ The following settings control this behavior.
 
 [NOTE]
 ====
-Since version 5.2, Hibernate allows overriding the global JDBC batch size given by the `hibernate.jdbc.batch_size` configuration property for a given `Session`.
+Since version 5.2, Hibernate allows overriding the global JDBC batch size given by the `hibernate.jdbc.batch_size` configuration property on a per `Session` basis.
 ====
 
 [[batch-session-jdbc-batch-size-example]]
@@ -73,7 +73,7 @@ There are several problems associated with this example:
 . JDBC batching is not enabled by default, so every insert statement requires a database roundtrip.
   To enable JDBC batching, set the `hibernate.jdbc.batch_size` property to an integer between 10 and 50.
 
-[NOTE]
+[IMPORTANT]
 ====
 Hibernate disables insert batching at the JDBC level transparently if you use an identity identifier generator.
 ====
@@ -175,7 +175,7 @@ DELETE FROM EntityName e WHERE e.name = ?
 
 [NOTE]
 ====
-The `FROM` and `WHERE` clauses are each optional, but it's good practice to use them.
+Although the `FROM` and `WHERE` clauses are optional, it is good practice to declare them explicitly.
 ====
 
 The `FROM` clause can only refer to a single entity, which can be aliased.
@@ -220,7 +220,7 @@ include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-update-version-example]
 
 [NOTE]
 ====
-If you use the `VERSIONED` statement, you cannot use custom version types, which use class `org.hibernate.usertype.UserVersionType`.
+If you use the `VERSIONED` statement, you cannot use custom version types that implement the `org.hibernate.usertype.UserVersionType`.
 
 This feature is only available in HQL since it's not standardized by JPA.
 ====
@@ -394,7 +394,7 @@ So, the entity identifiers are selected first and used for each particular updat
 [TIP]
 ====
 The IN clause row value expression has long been supported by Oracle, PostgreSQL, and nowadays by MySQL 5.7.
-However, SQL Server 2014 does not support this syntax, so you'll have to use a different strategy.
+However, SQL Server 2014 does not support it, so you'll have to use a different strategy.
 ====
 
 [[batch-bulk-hql-strategies-InlineIdsSubSelectValueListBulkIdStrategy]]
@@ -422,8 +422,8 @@ include::{extrasdir}/batch-bulk-hql-InlineIdsSubSelectValueListBulkIdStrategy-de
 
 [TIP]
 ====
-The underlying database must support the VALUES list clause, like PostgreSQL or SQL Server 2008.
-However, this strategy requires the IN-clause row value expression for composite identifiers so you can use this strategy only with PostgreSQL.
+The underlying database must support the `VALUES` list clause, like PostgreSQL or SQL Server 2008.
+However, this strategy requires the IN-clause row value expression for composite identifiers, and for this reason, you can only use the `InlineIdsSubSelectValueListBulkIdStrategy` strategy with PostgreSQL.
 ====
 
 [[batch-bulk-hql-strategies-InlineIdsOrClauseBulkIdStrategy]]
@@ -451,7 +451,7 @@ include::{extrasdir}/batch-bulk-hql-InlineIdsOrClauseBulkIdStrategy-delete-query
 
 [TIP]
 ====
-This strategy has the advantage of being supported by all the major relational database systems (e.g. Oracle, SQL Server, MySQL, and PostgreSQL).
+The `InlineIdsOrClauseBulkIdStrategy` strategy has the advantage of being supported by all the major relational database systems (e.g. Oracle, SQL Server, MySQL, and PostgreSQL).
 ====
 
 [[batch-bulk-hql-strategies-CteValuesListBulkIdStrategy]]
@@ -479,7 +479,8 @@ include::{extrasdir}/batch-bulk-hql-CteValuesListBulkIdStrategy-delete-query-exa
 
 [TIP]
 ====
-The underlying database must support the CTE (Common Table Expressions) that can be referenced from non-query statements as well, like PostgreSQL since 9.1 or SQL Server since 2005.
+The underlying database must support CTE (Common Table Expressions) that can be referenced from non-query statements as well. For instance, PostgreSQL supports this feature since version 9.1 and SQL Server offers support for it since version 2005.
+
 The underlying database must also support the VALUES list clause, like PostgreSQL or SQL Server 2008.
 
 However, this strategy requires the IN-clause row value expression for composite identifiers, so you can only use this strategy only with PostgreSQL.

documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc

@@ -10,13 +10,6 @@ The term bootstrapping refers to initializing and starting a software component.
 In Hibernate, we are specifically talking about the process of building a fully functional `SessionFactory` instance or `EntityManagerFactory` instance, for JPA.
 The process is very different for each.
 
-[NOTE]
-====
-This chapter will not focus on all the possibilities of bootstrapping.
-Those will be covered in each specific more-relevant chapters later on.
-Instead, we focus here on the API calls needed to perform the bootstrapping.
-====
-
 [TIP]
 ====
 During the bootstrap process, you might want to customize Hibernate behavior so make sure you check the <<appendices/Configurations.adoc#configurations,Configurations>> section as well.
@@ -47,7 +40,7 @@ This is a very powerful service, but a full discussion of it is beyond the scope
 [NOTE]
 ====
 If you are ok with the default behavior of Hibernate in regards to these `BootstrapServiceRegistry` services
-(which is quite often the case, especially in stand-alone environments), then building the `BootstrapServiceRegistry` can be skipped.
+(which is quite often the case, especially in stand-alone environments), then you don't need to explicitly build the `BootstrapServiceRegistry`.
 ====
 
 If you wish to alter how the `BootstrapServiceRegistry` is built, that is controlled through the `org.hibernate.boot.registry.BootstrapServiceRegistryBuilder:`

documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc

@@ -10,8 +10,9 @@ It is possible to configure a JVM-level (`SessionFactory`-level) or even a clust
 
 [NOTE]
 ====
-Be aware that caches are not aware of changes made to the persistent store by other applications.
-They can, however, be configured to regularly expire cached data.
+Be aware that Hibernate caches are not aware of changes made to the persistent store by other applications.
+
+To address this limitation, you can configure a TTL (Time To Live) retention policy at the second-level cache region level so that the underlying cache entries expire regularly.
 ====
 
 [[caching-config]]
@@ -114,8 +115,9 @@ transactional::
 
 [NOTE]
 ====
-Rather than using a global cache concurrency strategy, it is recommended to define this setting on a per entity basis.
-Use the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for that.
+Rather than using a global setting, it is recommended to define the cache concurrency strategy on a per entity basis.
+
+Use the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for this purpose.
 ====
 
 The `@Cache` annotation define three attributes:
@@ -146,10 +148,9 @@ ____
 
 [NOTE]
 ====
-As of Hibernate ORM 5.3, it's now possible to possible to override a base class `@Cacheable` or `@Cache` definition in subclasses.
+As of Hibernate ORM 5.3, you can now override a base class `@Cacheable` or `@Cache` definition at subclass level.
 
-However, the Hibernate cache concurrency strategy (e.g. read-only, nonstrict-read-write, read-write, transactional) is still defined at the root entity level
-and cannot be overridden.
+However, the Hibernate cache concurrency strategy (e.g. read-only, nonstrict-read-write, read-write, transactional) is still defined at the root entity level and cannot be overridden.
 ====
 
 Nevertheless, the reasons why we advise you to have all entities belonging to an inheritance tree share the same caching definition can be summed as follows:
@@ -305,10 +306,13 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-native-example
 
 [NOTE]
 ====
-The query cache does not cache the state of the actual entities in the cache;
-it caches only identifier values and results of value type.
+
+
+For entity queries, the query cache does not cache the state of the actual entities. Instead, it stores the entity identifiers, and when the query result is fetched from the cache, the entity state is going to be loaded from the second-level cache entity regions.
 
 Just as with collection caching, the query cache should always be used in conjunction with the second-level cache for those entities expected to be cached as part of a query result cache.
+
+For projection queries, the query cache stores the dehydrated entity state (e.g. `Object[]`) associated with the underlying JDBC `ResultSet`.
 ====
 
 [[caching-query-region]]
@@ -326,7 +330,7 @@ This setting creates two new cache regions:
 ====
 If you configure your underlying cache implementation to use expiration, it's very important
 that the timeout of the underlying cache region for the `default-update-timestamps-region`
-is set to a higher value than the timeouts of any of the query caches.
+is set to a higher value than the timeout setting of any of the query caches.
 
 In fact, we recommend that the `default-update-timestamps-region` region is not configured for expiration (time-based) or eviction (size/memory-based) at all.
 Note that an LRU (Least Recently Used) cache eviction policy is never appropriate for this particular cache region.
@@ -379,7 +383,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-m
 When using https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CacheStoreMode.html#REFRESH[`CacheStoreMode.REFRESH`] or https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/CacheMode.html#REFRESH[`CacheMode.REFRESH`] in conjunction with the region you have defined for the given query,
 Hibernate will selectively force the results cached in that particular region to be refreshed.
 
-This is particularly useful in cases where underlying data may have been updated via a separate process
+This behavior is particularly useful in cases when the underlying data may have been updated via a separate process
 and is a far more efficient alternative to the bulk eviction of the region via `SessionFactory` eviction which looks as follows:
 
 [source, JAVA, indent=0]
@@ -507,8 +511,9 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-statistics-example]
 
 [NOTE]
 ====
-Use of the built-in integration for https://jcp.org/en/jsr/detail?id=107[JCache] requires that the `hibernate-jcache` module jar (and all of its dependencies) are on the classpath.
-In addition a JCache implementation needs to be added as well.
+To use the built-in integration for https://jcp.org/en/jsr/detail?id=107[JCache], you need the `hibernate-jcache` module jar (and all of its dependencies) to be on the classpath.
+
+In addition, a JCache implementation needs to be added as well.
 A list of compatible implementations can be found https://jcp.org/aboutJava/communityprocess/implementations/jsr107/index.html[on the JCP website].
 An alternative source of compatible implementations can be found through https://github.com/cruftex/jsr107-test-zoo[the JSR-107 test zoo].
 ====
@@ -564,23 +569,21 @@ Only by specifying the second property `hibernate.javax.cache.uri` will you be a
 If you don't want to use the default `CacheManager`, you need to set the `hibernate.javax.cache.cache_manager` configuration property
 to one of the following values:
 
-Object reference:: If the value is an Object instance implementing the `CacheManager` interface,
+Object reference:: If the value is an `Object` instance implementing the `CacheManager` interface,
 the provided `CacheManager` instance will be used.
 `Class`:: If the value is a Java `Class` object that implements the `CacheManager` interface,
 Hibernate will create a new instance for that `Class` and use it instead of the default one.
 +
 [NOTE]
 ====
-The default no-arg constructor is going to be used, so make sure that the `CacheManager`
-implementation class provides it.
+When passing a Java `Class` that implements the `CacheManager` interface, you must make sure that the `CacheManager` implementation class provides a default no-arg constructor because that's going to be used to instantiate a `CacheManager` implementation `Object`.
 ====
 `String`:: If the value is a Java `String`, Hibernate expects it to be the fully-qualified `Class` name
 of the `CacheManager` implementation which will be used to instantiate the non-default `CacheManager`.
 +
 [NOTE]
 ====
-The default no-arg constructor is going to be used, so make sure that the `CacheManager`
-implementation class provides it.
+When passing the fully-qualified class name, you must make sure that the associated `Class` type provides a default no-arg constructor because that's going to be used to instantiate a `CacheManager` implementation `Object`.
 ====
 
 [[caching-provider-jcache-missing-cache-strategy]]
@@ -606,11 +609,9 @@ and also log a warning about the missing cache.
 
 [WARNING]
 ====
-Note that caches created this way may be very badly configured (unlimited size and no eviction in particular)
-unless the cache provider was explicitly configured to use a specific configuration for default caches.
+Note that caches created this way may not be suitable for production usage (unlimited size and no eviction in particular) unless the cache provider explicitly provides a specific configuration for default caches.
 
-Ehcache, in particular, allows to set such default configuration using cache templates,
-see http://www.ehcache.org/documentation/3.0/107.html#supplement-jsr-107-configurations
+Ehcache, in particular, allows to set such default configuration using cache templates. See the http://www.ehcache.org/documentation/3.0/107.html#supplement-jsr-107-configurations[Ehcache documentation] for more details.
 ====
 
 [[caching-provider-ehcache]]
@@ -668,7 +669,7 @@ shared among multiple `SessionFactory` instances in the same JVM.
 
 [NOTE]
 ====
-http://www.ehcache.org/documentation/2.8/integrations/hibernate#optional[Ehcache documentation] recommends using multiple non-singleton `CacheManager(s)` when there are multiple Hibernate `SessionFactory` instances running in the same JVM.
+The http://www.ehcache.org/documentation/2.8/integrations/hibernate#optional[Ehcache documentation] recommends using multiple non-singleton `CacheManager(s)` when there are multiple Hibernate `SessionFactory` instances running in the same JVM.
 ====
 
 [[caching-provider-ehcache-missing-cache-strategy]]
@@ -694,8 +695,7 @@ and also log a warning about the missing cache.
 
 [WARNING]
 ====
-Note that caches created this way may be very badly configured (large size in particular)
-unless an appropriate `<defaultCache>` entry is added to the Ehcache configuration.
+Note that caches created this way may be very badly configured (large size in particular) unless an appropriate `<defaultCache>` entry is added to the Ehcache configuration.
 ====
 
 [[caching-provider-infinispan]]

documentation/src/main/asciidoc/userguide/chapters/domain/access.adoc

@@ -10,8 +10,9 @@ When placed on the identifier getter, Hibernate will use property-based access.
 
 [IMPORTANT]
 ====
-You should pay attention to https://docs.oracle.com/javase/8/docs/api/java/beans/Introspector.html#decapitalize(java.lang.String)[Java Beans specification] in regard to naming properties to avoid
-issues such as https://hibernate.atlassian.net/browse/HCANN-63[Property name beginning with at least two uppercase characters has odd functionality in HQL]!
+To avoid issues such as
+https://hibernate.atlassian.net/browse/HCANN-63[HCANN-63 - Property name beginning with at least two uppercase characters has odd functionality in HQL], you should pay attention to
+https://docs.oracle.com/javase/8/docs/api/java/beans/Introspector.html#decapitalize(java.lang.String)[Java Bean specification] in regard to naming properties.
 ====
 
 Embeddable types inherit the access strategy from their parent entities.
@@ -34,7 +35,9 @@ To exclude a field from being part of the entity persistent state, the field mus
 [NOTE]
 ====
 Another advantage of using field-based access is that some entity attributes can be hidden from outside the entity.
+
 An example of such attribute is the entity `@Version` field, which, usually, does not need to be manipulated by the data access layer.
+
 With field-based access, we can simply omit the getter and the setter for this version field, and Hibernate can still leverage the optimistic concurrency control mechanism.
 ====