GraphParser warnings

hibernate-core/src/main/java/org/hibernate/graph/Graph.java

@@ -32,6 +32,13 @@
  * combine creation of a subgraph with creation of a treated subgraph.
  * <p>
  * Extends the JPA-defined {@link jakarta.persistence.Graph} with additional operations.
+ * <p>
+ * There are a range of ways to create {@code Graph}s:
+ * <ul>
+ * <li>programmatically, beginning with {@link org.hibernate.Session#createEntityGraph(Class)},
+ * <li>using the {@link jakarta.persistence.NamedEntityGraph @NamedEntityGraph} annotation, or
+ * <li>using the mini-language understood by {@link GraphParser}.
+ * </ul>
  *
  * @apiNote Historically, both {@link jakarta.persistence.EntityGraph} and this interface
  * declared operations with incorrect generic types, leading to unsound code. This was
@@ -46,6 +53,8 @@
  * @see SubGraph
  * @see jakarta.persistence.EntityGraph
  * @see jakarta.persistence.Subgraph
+ * @see GraphParser
+ * @see EntityGraphs
  */
 public interface Graph<J> extends GraphNode<J>, jakarta.persistence.Graph<J> {
 

hibernate-core/src/main/java/org/hibernate/graph/GraphParser.java

@@ -17,15 +17,17 @@
 /**
  * Parser for string representations of JPA {@link jakarta.persistence.EntityGraph}
  * ({@link RootGraph}) and {@link jakarta.persistence.Subgraph} ({@link SubGraph}),
- * using a simple syntax defined by the `graph.g` Antlr grammar.
+ * using a simple syntax defined by the {@code graph.g} ANTLR grammar. For example:
+ * <pre>employees(username, password, accessLevel, department(employees(username)))</pre>
  * <p>
  * The {@link #parse} methods all create a root {@link jakarta.persistence.EntityGraph}
  * based on the passed entity class and parse the graph string into that root graph.
  * <p>
  * The {@link #parseInto} methods parse the graph string into a passed graph, which may be a subgraph
  * <p>
- * Multiple graphs made for the same entity type can be merged.
- * See {@link EntityGraphs#merge(EntityManager, Class, jakarta.persistence.Graph...)}.
+ * Multiple graphs for the same entity type can be
+ * {@linkplain EntityGraphs#merge(EntityManager, Class, jakarta.persistence.Graph...)
+ * merged}.
  *
  * @author asusnjar
  */

hibernate-core/src/main/java/org/hibernate/graph/internal/parse/GraphParser.java

@@ -8,6 +8,7 @@
 import org.hibernate.grammars.graph.GraphLanguageLexer;
 import org.hibernate.grammars.graph.GraphLanguageParser;
 import org.hibernate.grammars.graph.GraphLanguageParserBaseVisitor;
+import org.hibernate.graph.GraphNode;
 import org.hibernate.graph.InvalidGraphException;
 import org.hibernate.graph.spi.AttributeNodeImplementor;
 import org.hibernate.graph.spi.GraphImplementor;
@@ -24,7 +25,7 @@
 /**
  * @author Steve Ebersole
  */
-public class GraphParser extends GraphLanguageParserBaseVisitor {
+public class GraphParser extends GraphLanguageParserBaseVisitor<GraphNode<?>> {
 
 	/**
 	 * Parse the passed graph textual representation into the passed Graph.
@@ -64,16 +65,16 @@ public static void parseInto(
 
 	private final SessionFactoryImplementor sessionFactory;
 
-	private final Stack<GraphImplementor> graphStack = new StandardStack<>();
-	private final Stack<AttributeNodeImplementor> attributeNodeStack = new StandardStack<>();
+	private final Stack<GraphImplementor<?>> graphStack = new StandardStack<>();
+	private final Stack<AttributeNodeImplementor<?,?,?>> attributeNodeStack = new StandardStack<>();
 	private final Stack<SubGraphGenerator> graphSourceStack = new StandardStack<>();
 
 	public GraphParser(SessionFactoryImplementor sessionFactory) {
 		this.sessionFactory = sessionFactory;
 	}
 
 	@Override
-	public AttributeNodeImplementor visitAttributeNode(GraphLanguageParser.AttributeNodeContext ctx) {
+	public AttributeNodeImplementor<?,?,?> visitAttributeNode(GraphLanguageParser.AttributeNodeContext ctx) {
 		final String attributeName = ctx.attributePath().ATTR_NAME().getText();
 
 		final SubGraphGenerator subGraphCreator;
@@ -105,7 +106,7 @@ public AttributeNodeImplementor visitAttributeNode(GraphLanguageParser.Attribute
 			subGraphCreator = pathQualifierType.getSubGraphCreator();
 		}
 
-		final AttributeNodeImplementor attributeNode = resolveAttributeNode( attributeName );
+		final AttributeNodeImplementor<?,?,?> attributeNode = resolveAttributeNode( attributeName );
 
 		if ( ctx.subGraph() != null ) {
 			attributeNodeStack.push( attributeNode );
@@ -132,12 +133,11 @@ public AttributeNodeImplementor visitAttributeNode(GraphLanguageParser.Attribute
 		return attributeNode;
 	}
 
-
-	private AttributeNodeImplementor resolveAttributeNode(String attributeName) {
+	private AttributeNodeImplementor<?,?,?> resolveAttributeNode(String attributeName) {
 		final GraphImplementor<?> currentGraph = graphStack.getCurrent();
 		assert currentGraph != null;
 
-		final AttributeNodeImplementor attributeNode = currentGraph.findOrCreateAttributeNode( attributeName );
+		final AttributeNodeImplementor<?,?,?> attributeNode = currentGraph.findOrCreateAttributeNode( attributeName );
 		assert attributeNode != null;
 
 		return attributeNode;
@@ -156,7 +156,7 @@ private PathQualifierType resolvePathQualifier(String qualifier) {
 	}
 
 	@Override
-	public SubGraphImplementor visitSubGraph(GraphLanguageParser.SubGraphContext ctx) {
+	public SubGraphImplementor<?> visitSubGraph(GraphLanguageParser.SubGraphContext ctx) {
 		final String subTypeName = ctx.subType() == null ? null : ctx.subType().getText();
 
 		if ( PARSING_LOGGER.isDebugEnabled() ) {