symfony
diff --git a/‎components/options_resolver.rst
Copy file name to clipboardExpand all lines: components/options_resolver.rst
+11Lines changed: 11 additions & 0 deletions b/‎components/options_resolver.rst
Copy file name to clipboardExpand all lines: components/options_resolver.rst
+11Lines changed: 11 additions & 0 deletions
@@ -654,6 +654,12 @@ method::
         ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
     ;
 
+.. note::
+
+    The deprecation message will be triggered only if the option is being used
+    somewhere, either its value is provided by the user or the option is evaluated
+    within closures of lazy options and normalizers.
+
 Instead of passing the message, you may also pass a closure which returns
 a string (the deprecation message) or an empty string to ignore the deprecation.
 This closure is useful to only deprecate some of the allowed types or values of
@@ -677,6 +683,11 @@ the option::
         })
     ;
 
+.. note::
+
+    Deprecation based on the value is triggered only when the option is provided
+    by the user.
+
 This closure receives as argument the value of the option after validating it
 and before normalizing it when the option is being resolved.