@@ -654,6 +654,12 @@ method::
654654 ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
655655 ;
656656
657+ ..note ::
658+
659+ The deprecation message will be triggered only if the option is being used
660+ somewhere, either its value is provided by the user or the option is evaluated
661+ within closures of lazy options and normalizers.
662+
657663Instead of passing the message, you may also pass a closure which returns
658664a string (the deprecation message) or an empty string to ignore the deprecation.
659665This closure is useful to only deprecate some of the allowed types or values of
@@ -677,6 +683,11 @@ the option::
677683 })
678684 ;
679685
686+ ..note ::
687+
688+ Deprecation based on the value is triggered only when the option is provided
689+ by the user.
690+
680691This closure receives as argument the value of the option after validating it
681692and before normalizing it when the option is being resolved.
682693