Introduce support for keyword arguments

[flavorjones]

The Nokogiri API was largely designed and implemented for Ruby 1.9, which pre-dates keyword argument support and parameter forwarding with .... As a result, many methods are using positional arguments where keyword arguments are probably better.

For example, Nokogiri::XML::Document.parse is declared as:

def parse(string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML)

I would like to update these method signatures to support keyword arguments without dropping support (yet) for positional arguments. In the case of Document.parse, this might look like:

def parse(string_or_io,
          url_ = nil, encoding_ = nil, options_ = XML::ParseOptions::DEFAULT_XML,
          url: url_, encoding: encoding_, options: options_)

I would also like to update the docstrings to describe the keyword arguments, and remove documentation for the positional arguments.

Another example is Nokogiri::XML() which is defined as:

def XML(thing, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_XML, &block)
  Nokogiri::XML::Document.parse(thing, url, encoding, options, &block)
end

Methods that are forwarding positional arguments should be updated to more cleanly forward either keyword arguments or positional arguments, and avoid redeclaring parameter default values:

def XML(...)
  Nokogiri::XML::Document.parse(...)
end

[flavorjones]

For an example of the kind of documentation I'd like to see, take a look at #3324 which updates Nokogiri::XML::Document.parse.

[flavorjones]

The list of methods that need to be updated is at https://docs.google.com/spreadsheets/d/1pWM7N5D9073J8IRVO0yghIySTYhsJoO73sslAVxEO-A/edit?gid=0#gid=0

We'll work on this for RubyConf 2024 hack day!

[flavorjones]

TODO: link back to this issue in doc strings for people to discover some documentation about the positional arguments