Clarify RootBeanDefinition vs GenericBeanDefinition

Closes gh-30444

spring-beans/src/main/java/org/springframework/beans/factory/support/GenericBeanDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,15 +21,17 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * GenericBeanDefinition is a one-stop shop for standard bean definition purposes.
- * Like any bean definition, it allows for specifying a class plus optionally
+ * GenericBeanDefinition is a one-stop shop for declarative bean definition purposes.
+ * Like all common bean definitions, it allows for specifying a class plus optionally
  * constructor argument values and property values. Additionally, deriving from a
  * parent bean definition can be flexibly configured through the "parentName" property.
  *
  * <p>In general, use this {@code GenericBeanDefinition} class for the purpose of
- * registering user-visible bean definitions (which a post-processor might operate on,
- * potentially even reconfiguring the parent name). Use {@code RootBeanDefinition} /
- * {@code ChildBeanDefinition} where parent/child relationships happen to be pre-determined.
+ * registering declarative bean definitions (e.g. XML definitions which a bean
+ * post-processor might operate on, potentially even reconfiguring the parent name).
+ * Use {@code RootBeanDefinition}/{@code ChildBeanDefinition} where parent/child
+ * relationships happen to be pre-determined, and prefer {@link RootBeanDefinition}
+ * specifically for programmatic definitions derived from factory methods/suppliers.
  *
  * @author Juergen Hoeller
  * @since 2.5

spring-beans/src/main/java/org/springframework/beans/factory/support/RootBeanDefinition.java

@@ -35,17 +35,23 @@
 import org.springframework.util.Assert;
 
 /**
- * A root bean definition represents the merged bean definition that backs
- * a specific bean in a Spring BeanFactory at runtime. It might have been created
- * from multiple original bean definitions that inherit from each other,
- * typically registered as {@link GenericBeanDefinition GenericBeanDefinitions}.
+ * A root bean definition represents the <b>merged bean definition at runtime</b>
+ * that backs a specific bean in a Spring BeanFactory. It might have been created
+ * from multiple original bean definitions that inherit from each other, e.g.
+ * {@link GenericBeanDefinition GenericBeanDefinitions} from XML declarations.
  * A root bean definition is essentially the 'unified' bean definition view at runtime.
  *
- * <p>Root bean definitions may also be used for registering individual bean definitions
- * in the configuration phase. However, since Spring 2.5, the preferred way to register
- * bean definitions programmatically is the {@link GenericBeanDefinition} class.
- * GenericBeanDefinition has the advantage that it allows to dynamically define
- * parent dependencies, not 'hard-coding' the role as a root bean definition.
+ * <p>Root bean definitions may also be used for <b>registering individual bean
+ * definitions in the configuration phase.</b> This is particularly applicable for
+ * programmatic definitions derived from factory methods (e.g. {@code @Bean} methods)
+ * and instance suppliers (e.g. lambda expressions) which come with extra type metadata
+ * (see {@link #setTargetType(ResolvableType)}/{@link #setResolvedFactoryMethod(Method)}).
+ *
+ * <p>Note: The preferred choice for bean definitions derived from declarative sources
+ * (e.g. XML definitions) is the flexible {@link GenericBeanDefinition} variant.
+ * GenericBeanDefinition comes with the advantage that it allows for dynamically
+ * defining parent dependencies, not 'hard-coding' the role as a root bean definition,
+ * even supporting parent relationship changes in the bean post-processor phase.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller