From e30ae7a240a3e9f6e19b71354d87dd0ab150fa98 Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <andy.wilkinson@broadcom.com>
Date: Fri, 6 Sep 2024 14:22:40 +0100
Subject: [PATCH] Document problem with property binding and Kotlin value
 classes

Closes gh-41693
---
 .../spring-boot-docs/src/docs/asciidoc/features/kotlin.adoc | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/kotlin.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/kotlin.adoc
index a50eb957cc2..812ee7a1e74 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/kotlin.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/kotlin.adoc
@@ -108,7 +108,7 @@ TIP: `org.jetbrains.kotlinx:kotlinx-coroutines-reactor` dependency is provided b
 
 [[features.kotlin.configuration-properties]]
 === @ConfigurationProperties
-`@ConfigurationProperties` when used in combination with <<features#features.external-config.typesafe-configuration-properties.constructor-binding,constructor binding>> supports classes with immutable `val` properties as shown in the following example:
+`@ConfigurationProperties` when used in combination with <<features#features.external-config.typesafe-configuration-properties.constructor-binding,constructor binding>> supports data classes with immutable `val` properties as shown in the following example:
 
 [source,kotlin,indent=0,subs="verbatim"]
 ----
@@ -125,6 +125,10 @@ data class KotlinExampleProperties(
 }
 ----
 
+Due to the limitations of their interoperability with Java, support for value classes is limited.
+In particular, relying upon a value class's default value will not work with configuration property binding.
+In such cases, a data class should be used instead.
+
 TIP: To generate <<configuration-metadata#appendix.configuration-metadata.annotation-processor,your own metadata>> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency.
 Note that some features (such as detecting the default value or deprecated items) are not working due to limitations in the model kapt provides.