further improvements to jdoc of @find and @hql

Author: gavinking

hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java

@@ -47,6 +47,14 @@
  *     encode no semantics.
  * </ul>
  * <p>
+ * It's even possible to query by a field of an embedded object:
+ * <pre>
+ * &#064;Find
+ * List&lt;Book&gt; publishedBooks(String publisher$name);
+ * </pre>
+ * Here, {@code publisher$name} refers to the field {@code name} of
+ * the {@code Book}'s {@code Publisher}.
+ * <p>
  * The Metamodel Generator automatically creates an "implementation"
  * of every finder method in the static metamodel class {@code Books_}.
  * The generated method may be called according to the following
@@ -133,6 +141,12 @@
  *     (varargs) where {@code E} is the entity type returned by the
  *     query.
  * </ul>
+ * <p>
+ * For example:
+ * <pre>
+ * &#064;Find
+ * List&lt;Book&gt; getBooksWithTitle(String title, List&lt;Order&lt;Book&gt;&gt; order);
+ * </pre>
  *
  * @see HQL
  * @see SQL

hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java

@@ -23,13 +23,13 @@
  * For example:
  * <pre>
  * public interface Books {
- *     &#64;HQL("from Book where isbn = :isbn")
+ *     &#64;HQL("where isbn = :isbn")
  *     Book findBookByIsbn(String isbn);
  *
- *     &#64;HQL("from Book where title like ?1 order by title offset ?3 fetch first ?2 rows only")
+ *     &#64;HQL("where title like ?1 order by title offset ?3 fetch first ?2 rows only")
  *     List&lt;Book&gt; findBooksByTitleWithPagination(String title, int max, int start);
  *
- *     &#64;HQL("from Book where title like ?1")
+ *     &#64;HQL("where title like ?1")
  *     TypedQuery&lt;Book&gt; createBooksByTitleQuery(String title);
  * }
  * </pre>
@@ -111,6 +111,12 @@
  *     query.
  * </ul>
  * <p>
+ * For example:
+ * <pre>
+ * &#64;HQL("where title like :title)
+ * List&lt;Book&gt; findBooksByTitleWithPagination(String title, Page page, Order&lt;Book&gt; order);
+ * </pre>
+ * <p>
  * Queries specified using this annotation are always validated by
  * the Metamodel Generator, and so it isn't necessary to specify the
  * {@link CheckHQL} annotation.