Add support for descriptions of record components in configuration metadata generation

[An1s9n]

Hello everyone!

While working on PR #29010 I've noticed that now there is no way to automatically generate descriptions in configuration metadata if you use @ConfigurationProperties with record class. Indeed, there are no explicit fields to put regular field-level Javadocs on. But there is an official way for records to do so: descriptions should be provided via class-level Javadoc tag @param.

I've added support for such usage, added test and mentioned it in reference documentation. I assume test is clear enough for understanding what I've done. Hope build will pass :)

[wilkinsona]

Thanks for the PR, @An1s9n.

While looking at this I noticed some existing problems with detecting deprecated record components and opened #29526. We somewhat accidentally fell into using ConstructorParameterPropertyDescriptor for records because, on the surface at least, it just worked. Looking a little deeper, we're now noticing things that aren't working correctly and it has become apparent that we need to handle property descriptions (this PR) and property deprecation (#29526) differently.

I think we need to take a bit of a step back and review how we're handling records in general. My suspicion at the moment is that we'll either want separate property description classes for records and classes or we'll want to use composition a bit more so that we can plug in strategies for identifying property accessors and extract property descriptions from javadoc. I'm going to put this one on hold until we've had a chance to do that.

[Peksa]

Hi! Has there been any updates and/or design work on this?

[wilkinsona]

No, not yet I'm afraid. Updates will appear here or in a linked issue when we have them.

[philwebb]

Thanks very much for the PR @An1s9n, and for your patience whilst we got around to merging it.

I've just merged this into main so that it will be available as part of the 3.3 release. Ordinarily we wouldn't make changes like this post RC, but I think it's worth making an exception for this one since it's relatively isolated and a lot of folks have voted on the issue.

For anyone watching this issue, please give the SNAPSHOT a try (when https://github.com/spring-projects/spring-boot/actions/runs/8788352195 has finished) and let us know if there are problems. We have a few weeks to iron out any issues.