[rb] allow deprecation logging to provide link to additional references

Author: titusfortner

rb/lib/selenium/webdriver/common/logger.rb

@@ -108,10 +108,11 @@ def warn(message, id: [])
       #
       # @param [String] old
       # @param [String, nil] new
-      # @param [Symbol, Array<Sybmol>] id
+      # @param [Symbol, Array<Symbol>] id
+      # @param [String] reference
       # @yield appends additional message to end of provided template
       #
-      def deprecate(old, new = nil, id: [], &block)
+      def deprecate(old, new = nil, id: [], reference: '', &block)
         id = Array(id)
         return if @ignored.include?(:deprecations) || (@ignored & id).any?
 
@@ -123,6 +124,8 @@ def deprecate(old, new = nil, id: [], &block)
                    else
                      ' and will be removed in a future release.'
                    end
+        message << " See explanation for this deprecation: #{reference}." unless reference.empty?
+
         warn message, &block
       end
 

rb/spec/unit/selenium/webdriver/common/logger_spec.rb

@@ -106,6 +106,13 @@ module WebDriver
           expect { logger.deprecate('#old') }.to output(message).to_stdout_from_any_process
         end
 
+        it 'allows to deprecate functionality with a reference message' do
+          ref_url = 'https://selenium.dev'
+          warn_msg = 'WARN Selenium \[DEPRECATION\] #old is deprecated\. Use #new instead\.'
+          message = /#{warn_msg} See explanation for this deprecation: #{ref_url}/
+          expect { logger.deprecate('#old', '#new', reference: ref_url) }.to output(message).to_stdout_from_any_process
+        end
+
         it 'appends deprecation message with provided block' do
           message = /WARN Selenium \[DEPRECATION\] #old is deprecated\. Use #new instead\. More Details\./
           expect { logger.deprecate('#old', '#new') { 'More Details.' } }.to output(message).to_stdout_from_any_process