HHH-11186 - Add examples for all Hibernate annotations

Document @QueryHint

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

@@ -536,7 +536,7 @@ The http://docs.oracle.com/javaee/7/api/javax/persistence/PrimaryKeyJoinColumns.
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/QueryHint.html[`@QueryHint`] annotation is used to specify a JPA provider hint used by a `@NamedQuery` or a `@NamedNativeQuery` annotation.
 
-//TODO: Add example
+See the <<chapters/query/hql/HQL.adoc#jpa-read-only-entities-native-example, `@QueryHint`>> section for more info.
 
 [[annotations-jpa-secondarytable]]
 ==== `@SecondaryTable`

documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc

@@ -215,6 +215,7 @@ For complete details, see the https://docs.jboss.org/hibernate/orm/{majorMinorVe
 ====
 Query hints here are database query hints.
 They are added directly to the generated SQL according to `Dialect#getQueryHintString`.
+
 The JPA notion of query hints, on the other hand, refer to hints that target the provider (Hibernate).
 So even though they are called the same, be aware they have a very different purpose.
 Also, be aware that Hibernate query hints generally make the application non-portable across databases unless the code adding them first checks the Dialect.
@@ -1831,6 +1832,17 @@ include::{extrasdir}/hql-read-only-entities-example.sql[]
 
 As you can see, there is no SQL `UPDATE` being executed.
 
+You can also pass the read-only hint to named queries using the JPA http://docs.oracle.com/javaee/7/api/javax/persistence/QueryHint.html[`@QueryHint`] annotation.
+
+[[jpa-read-only-entities-native-example]]
+.Fetching read-only entities using a named query and the read-only hint
+====
+[source, JAVA, indent=0]
+----
+include::{modeldir}/Person.java[tags=jpa-read-only-entities-native-example]
+----
+====
+
 The Hibernate native API offers a `Query#setReadOnly` method, as an alternative to using a JPA query hint:
 
 [[hql-read-only-entities-native-example]]

documentation/src/main/java/org/hibernate/userguide/model/Person.java

@@ -31,6 +31,7 @@ import javax.persistence.NamedStoredProcedureQuery;
 import javax.persistence.OneToMany;
 import javax.persistence.OrderColumn;
 import javax.persistence.ParameterMode;
+import javax.persistence.QueryHint;
 import javax.persistence.SqlResultSetMapping;
 import javax.persistence.SqlResultSetMappings;
 import javax.persistence.StoredProcedureParameter;
@@ -151,14 +152,27 @@ import javax.persistence.Version;
     //end::sql-multiple-scalar-values-dto-NamedNativeQuery-example[]
 })
 //tag::hql-examples-domain-model-example[]
-//tag::jpql-api-named-query-example[]
+@NamedQueries({
-@NamedQueries(
+    //tag::jpql-api-named-query-example[]
     @NamedQuery(
         name = "get_person_by_name",
         query = "select p from Person p where name = :name"
     )
-)
+    //end::jpql-api-named-query-example[]
-//end::jpql-api-named-query-example[]
+    ,
+    // tag::jpa-read-only-entities-native-example[]
+    @NamedQuery(
+        name = "get_person_by_name",
+        query = "select p from Person p where name = :name",
+        hints = {
+            @QueryHint(
+                name = "org.hibernate.readOnly",
+                value = "true"
+            )
+        }
+    )
+    //end::jpa-read-only-entities-native-example[]
+})
 //tag::sql-sp-ref-cursor-oracle-named-query-example[]
 @NamedStoredProcedureQueries(
     @NamedStoredProcedureQuery(