From 277da462ced93d169b811e0ff37ed9ece0db756f Mon Sep 17 00:00:00 2001
From: Stephane Nicoll <snicoll@pivotal.io>
Date: Mon, 11 Jul 2016 12:23:30 +0200
Subject: [PATCH] Document differences between @Value and
 @ConfigurationProperties

Closes gh-4892
---
 .../main/asciidoc/spring-boot-features.adoc   | 41 ++++++++++++++++++-
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
index a81509a40c..1381d0d622 100644
--- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
+++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
@@ -734,8 +734,8 @@ Nested POJO properties can also be created (so a setter is not mandatory) if the
 default constructor, or a constructor accepting a single value that can be coerced from
 String. Some people use Project Lombok to add getters and setters automatically.
 
-NOTE: Contrary to `@Value`, SpEL expressions are not evaluated prior to injecting a value
-in the relevant `@ConfigurationProperties` bean.
+TIP: See also the <<boot-features-external-config-vs-value,differences between `@Value`
+and `@ConfigurationProperties`>>.
 
 The `@EnableConfigurationProperties` annotation is automatically applied to your project
 so that any beans annotated with `@ConfigurationProperties` will be configured from the
@@ -954,6 +954,43 @@ _<<production-ready-features.adoc#production-ready-endpoints, Production ready f
 section for details.
 
 
+
+[[boot-features-external-config-vs-value]]
+==== @ConfigurationProperties vs. @Value
+
+`@Value` is a core container feature and it does not provide the same features as type-safe
+Configuration Properties. The table below summarizes the features that are supported by
+`@ConfigurationProperties` and `@Value`:
+
+[cols="4,2,2"]
+|===
+|Feature |`@ConfigurationProperties` |`@Value`
+
+| <<boot-features-external-config-relaxed-binding,Relaxed binding>>
+| Yes
+| No
+
+| <<appendix-configuration-metadata.adoc#configuration-metadata,Meta-data support>>
+| Yes
+| No
+
+| `SpEL` evaluation
+| No
+| Yes
+
+|===
+
+If you define a set of configuration keys for your own components, we recommend you to
+group them in a pojo annotated with `@ConfigurationProperties`. Please also be aware
+that since `@Value` does not support relaxed binding, it isn't a great candidate if you
+need to provide the value using environment variables.
+
+Finally, while you can write a `SpEL` expression in `@Value`, such expressions are not
+processed from <<boot-features-external-config-application-property-files,Application
+property files>>.
+
+
+
 [[boot-features-profiles]]
 == Profiles
 Spring Profiles provide a way to segregate parts of your application configuration and