minor #10496 [OptionsResolver] Add some notes about trigger deprecation (yceruto)

xabbuh · xabbuh · commit 408ee2e7d310 · 2018-11-11T11:28:31.000+01:00
This PR was merged into the master branch. Discussion ---------- [OptionsResolver] Add some notes about trigger deprecation Updates according to symfony/symfony#28878 Commits ------- bb4861b Add some notes about trigger deprecation
diff --git a/components/options_resolver.rst b/components/options_resolver.rst
@@ -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.
 
