improve javadoc for EntityGraph

Signed-off-by: Gavin King <[email protected]>

api/src/main/java/jakarta/persistence/EntityGraph.java

@@ -24,6 +24,32 @@
  * The methods to add subgraphs implicitly create the corresponding
  * attribute nodes as well; such attribute nodes should not be
  * redundantly specified.
+ * <p>
+ * When used to specify fetching, an entity graph has two possible
+ * interpretations:
+ * <ul>
+ * <li>As a <em>load graph</em>, where every node explicitly added
+ *     to or explicitly removed from the graph overrides the
+ *     {@linkplain FetchType fetching strategy} of the attribute
+ *     which was specified via annotations or XML descriptor, but
+ *     the graph does not affect the fetching strategy of any
+ *     attribute which was neither added to nor removed from the
+ *     graph.
+ * <li>As a <em>fetch graph</em>, where the graph completely
+ *     overrides every fetching strategy specified via annotations
+ *     or XML descriptor, and every attribute not explicitly added
+ *     to the graph is treated as {@link FetchType#LAZY}.
+ * </ul>
+ * <p>
+ * An entity graph passed as the first argument to
+ * {@link EntityManager#find(EntityGraph, Object, FindOption...)}
+ * is interpreted as a load graph.
+ * <p>
+ * When an entity graph is passed to
+ * {@link EntityManager#refresh(Object, EntityGraph)}, the graph
+ * completely overrides the effect of {@code cascade=REFRESH}, and
+ * each node belonging to the graph is treated as an instruction
+ * to refresh the corresponding attribute.
  *
  * @param <T> The type of the root entity.
  *
@@ -36,6 +62,7 @@
  * @see EntityManager#getEntityGraph(String)
  * @see EntityManagerFactory#addNamedEntityGraph(String, EntityGraph)
  * @see EntityManager#find(EntityGraph, Object, FindOption...)
+ * @see EntityManager#refresh(Object, EntityGraph)
  *
  * @since 2.1
  */

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -2071,7 +2071,7 @@ When the `jakarta.persistence.loadgraph`
 property is used to specify an entity graph, attributes that are
 specified by attribute nodes of the entity graph are treated as
 `FetchType.EAGER` and attributes that are not specified are treated
-according to their specified or default FetchType.
+according to their specified or default `FetchType`.
 
 The following rules apply. The rules of this
 section are applied recursively.