Deprecate positional hash arguments in the API

[flavorjones]

Currently we've still got a few methods that use the pre-Ruby-3.0 convention of using a positional hash argument to pass options.

For example:

# lib/nokogiri/html5/document_fragment.rb
def initialize(doc, tags = nil, ctx = nil, options = {})
  ...
end

...

def self.parse(tags, encoding = nil, options = {})
  ...
end

I'd like to start planning to deprecate these positional hashes in favor of true keyword arguments.

Note that we can't simply move to keyword arguments, since calls that use explicit hashes would stop working:

Nokogiri::HTML5::DocumentFragment.parse(frag, nil, {max_errors: 1})
# ArgumentError: wrong number of arguments (given 3, expected 1..2)
#     lib/nokogiri/html5/document_fragment.rb:59:in `parse'

So we'll need to do an intermediate step that looks something like:

diff --git a/lib/nokogiri/html5/document_fragment.rb b/lib/nokogiri/html5/document_fragment.rb
index 1cd4b28d..6d3f1fe1 100644
--- a/lib/nokogiri/html5/document_fragment.rb
+++ b/lib/nokogiri/html5/document_fragment.rb
@@ -56,7 +56,12 @@ def serialize(options = {}, &block) # :nodoc:
       end
 
       # Parse a document fragment from +tags+, returning a Nodeset.
-      def self.parse(tags, encoding = nil, **options)
+      def self.parse(tags, encoding = nil, positional_options_hash = nil, **options)
+        unless positional_options_hash.nil?
+          warn("ClassName.methodname: Passing options as an explicit hash is deprecated. Use keyword arguments instead. This will become an error in a future release.", uplevel: 1, category: :deprecated)
+          options.merge!(positional_options_hash)
+        end
+
         doc = HTML5::Document.new
         tags = HTML5.read_and_encode(tags, encoding)
         doc.encoding = "UTF-8"

[flavorjones]

Closing this, related work at #3323 mostly addressed this in a backwards-compatible way.