Improve javadoc on TQRootBean and generated javadoc on query bean forFetchGroup() method

ebean-querybean/src/main/java/io/ebean/typequery/TQRootBean.java

@@ -213,20 +213,38 @@ public abstract class TQRootBean<T, R> {
   /**
    * Set a FetchGroup to control what part of the object graph is loaded.
    * <p>
-   * This is an alternative to using select() and fetch() providing a nice clean separation
-   * between what a query should load and the query predicates.
-   * </p>
+   * FetchGroup is immutable and threadsafe. We expect to create and store
+   * FetchGroup to a static final field and reuse the instance.
+   * <p>
+   * FetchGroup is an alternative to using select() and fetch() providing a nice
+   * clean separation between what a query should load and the query predicates.
    *
    * <pre>{@code
    *
-   * FetchGroup<Customer> fetchGroup = FetchGroup.of(Customer.class)
-   *   .select("name, status")
-   *   .fetch("contacts", "firstName, lastName, email")
-   *   .build();
+   * // immutable threadsafe
    *
-   * List<Customer> customers =
+   * static final FetchGroup<Customer> fetchGroup =
+   *   QCustomer.forFetchGroup()
+   *     .shippingAddress.fetch()
+   *     .contacts.fetch()
+   *     .buildFetchGroup();
    *
-   *   new QCustomer()
+   * List<Customer> customers = new QCustomer()
+   *   .select(fetchGroup)
+   *   .findList();
+   *
+   * }</pre>
+   *
+   *
+   * <pre>{@code
+   *
+   * static final FetchGroup<Customer> fetchGroup =
+   *   FetchGroup.of(Customer.class)
+   *     .select("name, status")
+   *     .fetch("contacts", "firstName, lastName, email")
+   *     .build();
+   *
+   * List<Customer> customers = new QCustomer()
    *   .select(fetchGroup)
    *   .findList();
    *

querybean-generator/src/main/java/io/ebean/querybean/generator/SimpleQueryBeanWriter.java

@@ -188,6 +188,24 @@ class SimpleQueryBeanWriter {
     writer.eol();
     writer.append("  /**").eol();
     writer.append("   * Return a query bean used to build a FetchGroup.").eol();
+    writer.append("   * <p>").eol();
+    writer.append("   * FetchGroups are immutable and threadsafe and can be used by many").eol();
+    writer.append("   * concurrent queries. We typically stored FetchGroup as a static final field.").eol();
+    writer.append("   * <p>").eol();
+    writer.append("   * Example creating and using a FetchGroup.").eol();
+    writer.append("   * <pre>{@code").eol();
+    writer.append("   * ").eol();
+    writer.append("   * static final FetchGroup<Customer> fetchGroup = ").eol();
+    writer.append("   *   QCustomer.forFetchGroup()").eol();
+    writer.append("   *     .shippingAddress.fetch()").eol();
+    writer.append("   *     .contacts.fetch()").eol();
+    writer.append("   *     .buildFetchGroup();").eol();
+    writer.append("   * ").eol();
+    writer.append("   * List<Customer> customers = new QCustomer()").eol();
+    writer.append("   *   .select(fetchGroup)").eol();
+    writer.append("   *   .findList();").eol();
+    writer.append("   * ").eol();
+    writer.append("   * }</pre>").eol();
     writer.append("   */").eol();
     writer.append("  public static Q%s forFetchGroup() {", shortName).eol();
     writer.append("    return new Q%s(FetchGroup.queryFor(%s.class));", shortName, shortName).eol();