add some @SInCE annotations and a lil' bit more Javadoc

Author: gavinking

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

@@ -68,11 +68,29 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	 */
 	Map<Class<?>, ? extends SubGraph<?>> getKeySubGraphs();
 
+	/**
+	 * All value subgraphs rooted at this node.
+	 * <p>
+	 * Includes treated subgraphs.
+	 *
+	 * @apiNote This operation is declared with raw types by JPA
+	 *
+	 * @see #getSubGraphs()
+	 */
 	@Override
 	default @SuppressWarnings("rawtypes") Map<Class, Subgraph> getSubgraphs() {
 		return unmodifiableMap( getSubGraphs() );
 	}
 
+	/**
+	 * All key subgraphs rooted at this node.
+	 * <p>
+	 * Includes treated subgraphs.
+	 *
+	 * @apiNote This operation is declared with raw types by JPA
+	 *
+	 * @see #getKeySubGraphs()
+	 */
 	@Override
 	default @SuppressWarnings("rawtypes") Map<Class, Subgraph> getKeySubgraphs() {
 		return unmodifiableMap( getKeySubGraphs() );
@@ -81,12 +99,22 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	/**
 	 * Create and return a new value {@link SubGraph} rooted at this node,
 	 * or return an existing such {@link SubGraph} if there is one.
+	 * <p>
+	 * Note that {@code graph.addAttributeNode(att).makeSubGraph()} is a
+	 * synonym for {@code graph.addSubgraph(att)}.
+	 *
+	 * @see Graph#addSubgraph(jakarta.persistence.metamodel.Attribute)
 	 */
 	SubGraph<?> makeSubGraph();
 
 	/**
 	 * Create and return a new key {@link SubGraph} rooted at this node,
 	 * or return an existing such {@link SubGraph} if there is one.
+	 * <p>
+	 * Note that {@code graph.addAttributeNode(att).makeKeySubGraph()} is a
+	 * synonym for {@code graph.addMapKeySubgraph(att)}.
+	 *
+	 * @see Graph#addMapKeySubgraph(jakarta.persistence.metamodel.MapAttribute)
 	 */
 	SubGraph<?> makeKeySubGraph();
 
@@ -97,8 +125,13 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	 * <p>
 	 * If the given type is a proper subtype of the value type, the result
 	 * is a treated subgraph.
+	 * <p>
+	 * Note that {@code graph.addAttributeNode(att).makeSubGraph(cl)}
+	 * is a synonym for {@code graph.addTreatedSubgraph(att,cl)}.
 	 *
 	 * @param subtype The type or treated type of the value type
+	 *
+	 * @see Graph#addTreatedSubgraph(jakarta.persistence.metamodel.Attribute, Class)
 	 */
 	<S> SubGraph<S> makeSubGraph(Class<S> subtype);
 
@@ -109,8 +142,13 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	 * <p>
 	 * If the given type is a proper subtype of the key type, the result
 	 * is a treated subgraph.
+	 * <p>
+	 * Note that {@code graph.addAttributeNode(att).makeKeySubGraph(cl)}
+	 * is a synonym for {@code graph.addTreatedMapKeySubgraph(att,cl)}.
 	 *
 	 * @param subtype The type or treated type of the key type
+	 *
+	 * @see Graph#addTreatedMapKeySubgraph(jakarta.persistence.metamodel.MapAttribute,Class)
 	 */
 	<S> SubGraph<S> makeKeySubGraph(Class<S> subtype);
 
@@ -123,6 +161,8 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	 * is a treated subgraph.
 	 *
 	 * @param subtype The type or treated type of the value type
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<S> SubGraph<S> makeSubGraph(ManagedType<S> subtype);
@@ -136,6 +176,8 @@ public interface AttributeNode<J> extends GraphNode<J>, jakarta.persistence.Attr
 	 * is a treated subgraph.
 	 *
 	 * @param subtype The type or treated type of the key type
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<S> SubGraph<S> makeKeySubGraph(ManagedType<S> subtype);

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

@@ -100,13 +100,17 @@ RootGraph<J> makeRootGraph(String name, boolean mutable)
 
 	/**
 	 * Find an existing {@link AttributeNode} by name within this container.
+	 *
+	 * @since 7.0
 	 */
 	@Override
 	<Y> AttributeNode<Y> getAttributeNode(String attributeName);
 
 	/**
 	 * Find an existing {@link AttributeNode} by corresponding attribute
 	 * reference, within this container.
+	 *
+	 * @since 7.0
 	 */
 	@Override
 	<Y> AttributeNode<Y> getAttributeNode(Attribute<? super J, Y> attribute);
@@ -145,13 +149,17 @@ RootGraph<J> makeRootGraph(String name, boolean mutable)
 	 * such {@link SubGraph} if there is one.
 	 *
 	 * @see jakarta.persistence.EntityGraph#addTreatedSubgraph(Class)
+	 *
+	 * @since 7.0
 	 */
 	<Y extends J> SubGraph<Y> addTreatedSubgraph(Class<Y> type);
 
 	/**
 	 * Create and return a new (mutable) {@link SubGraph} representing
 	 * the given subtype of the type of this node, or return an existing
 	 * such {@link SubGraph} if there is one.
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<Y extends J> SubGraph<Y> addTreatedSubgraph(ManagedType<Y> type);
@@ -244,6 +252,8 @@ <X> SubGraph<X> addSubgraph(Attribute<? super J, X> attribute)
 	 * @param type A subtype of the attribute type
 	 *
 	 * @see #addSubgraph(Attribute, Class)
+	 *
+	 * @since 7.0
 	 */
 	@Override
 	<Y> SubGraph<Y> addTreatedSubgraph(Attribute<? super J, ? super Y> attribute, Class<Y> type)
@@ -260,6 +270,8 @@ <Y> SubGraph<Y> addTreatedSubgraph(Attribute<? super J, ? super Y> attribute, Cl
 	 *
 	 * @param attribute An attribute of the represented type
 	 * @param type A subtype of the attribute type
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<AJ> SubGraph<AJ> addTreatedSubgraph(Attribute<? super J, ? super AJ> attribute, ManagedType<AJ> type)
@@ -337,6 +349,8 @@ <AJ> SubGraph<AJ> addSubGraph(PersistentAttribute<? super J, ? super AJ> attribu
 	 * {@link SubGraph} if there is one.
 	 *
 	 * @param attribute A collection-valued attribute of the represented type
+	 *
+	 * @since 7.0
 	 */
 	@Override
 	<E> SubGraph<E> addElementSubgraph(PluralAttribute<? super J, ?, E> attribute);
@@ -352,6 +366,8 @@ <AJ> SubGraph<AJ> addSubGraph(PersistentAttribute<? super J, ? super AJ> attribu
 	 *
 	 * @param attribute A collection-valued attribute of the represented type
 	 * @param type A subtype of the element type
+	 *
+	 * @since 7.0
 	 */
 	@Override
 	<E> SubGraph<E> addTreatedElementSubgraph(PluralAttribute<? super J, ?, ? super E> attribute, Class<E> type)
@@ -368,6 +384,8 @@ <E> SubGraph<E> addTreatedElementSubgraph(PluralAttribute<? super J, ?, ? super
 	 *
 	 * @param attribute A collection-valued attribute of the represented type
 	 * @param type A subtype of the element type
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<AJ> SubGraph<AJ> addTreatedElementSubgraph(PluralAttribute<? super J, ?, ? super AJ> attribute, ManagedType<AJ> type)
@@ -468,6 +486,8 @@ <AJ> SubGraph<AJ> addKeySubGraph(String attributeName, Class<AJ> type)
 	 *
 	 * @param attribute A map-valued attribute of the represented type
 	 * @param type A subtype of the key type
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<AJ> SubGraph<AJ> addTreatedMapKeySubgraph(MapAttribute<? super J, ? super AJ, ?> attribute, ManagedType<AJ> type)