nokogiri 1.15.1 → 1.16.5

data/ext/nokogiri/xml_text.c

@@ -9,33 +9,38 @@ VALUE cNokogiriXmlText ;
  * Create a new Text element on the +document+ with +content+
  */
 static VALUE
-new (int argc, VALUE *argv, VALUE klass)
+rb_xml_text_s_new(int argc, VALUE *argv, VALUE klass)
 {
-  xmlDocPtr doc;
-  xmlNodePtr node;
-  VALUE string;
-  VALUE document;
-  VALUE rest;
+  xmlDocPtr c_document;
+  xmlNodePtr c_node;
+  VALUE rb_string;
+  VALUE rb_document;
+  VALUE rb_rest;
   VALUE rb_node;
 
-  rb_scan_args(argc, argv, "2*", &string, &document, &rest);
+  rb_scan_args(argc, argv, "2*", &rb_string, &rb_document, &rb_rest);
 
-  if (rb_obj_is_kind_of(document, cNokogiriXmlDocument)) {
-    doc = noko_xml_document_unwrap(document);
-  } else {
+  if (!rb_obj_is_kind_of(rb_document, cNokogiriXmlNode)) {
+    rb_raise(rb_eTypeError,
+             "expected second parameter to be a Nokogiri::XML::Document, received %"PRIsVALUE,
+             rb_obj_class(rb_document));
+  }
+
+  if (!rb_obj_is_kind_of(rb_document, cNokogiriXmlDocument)) {
     xmlNodePtr deprecated_node_type_arg;
-    // TODO: deprecate allowing Node
-    NOKO_WARN_DEPRECATION("Passing a Node as the second parameter to Text.new is deprecated. Please pass a Document instead. This will become an error in a future release of Nokogiri.");
-    Noko_Node_Get_Struct(document, xmlNode, deprecated_node_type_arg);
-    doc = deprecated_node_type_arg->doc;
+    NOKO_WARN_DEPRECATION("Passing a Node as the second parameter to Text.new is deprecated. Please pass a Document instead. This will become an error in Nokogiri v1.17.0."); // TODO: deprecated in v1.15.3, remove in v1.17.0
+    Noko_Node_Get_Struct(rb_document, xmlNode, deprecated_node_type_arg);
+    c_document = deprecated_node_type_arg->doc;
+  } else {
+    c_document = noko_xml_document_unwrap(rb_document);
   }
 
-  node = xmlNewText((xmlChar *)StringValueCStr(string));
-  node->doc = doc;
+  c_node = xmlNewText((xmlChar *)StringValueCStr(rb_string));
+  c_node->doc = c_document;
 
-  noko_xml_document_pin_node(node);
+  noko_xml_document_pin_node(c_node);
 
-  rb_node = noko_xml_node_wrap(klass, node) ;
+  rb_node = noko_xml_node_wrap(klass, c_node) ;
   rb_obj_call_init(rb_node, argc, argv);
 
   if (rb_block_given_p()) { rb_yield(rb_node); }
@@ -52,5 +57,5 @@ noko_init_xml_text(void)
    */
   cNokogiriXmlText = rb_define_class_under(mNokogiriXml, "Text", cNokogiriXmlCharacterData);
 
-  rb_define_singleton_method(cNokogiriXmlText, "new", new, -1);
+  rb_define_singleton_method(cNokogiriXmlText, "new", rb_xml_text_s_new, -1);
 }

data/ext/nokogiri/xml_xpath_context.c

@@ -321,11 +321,8 @@ handler_lookup(void *data, const xmlChar *c_name, const xmlChar *c_ns_uri)
   VALUE rb_handler = (VALUE)data;
   if (rb_respond_to(rb_handler, rb_intern((const char *)c_name))) {
     if (c_ns_uri == NULL) {
-      NOKO_WARN_DEPRECATION(
-        "A custom XPath or CSS handler function named '%s' is being invoked without a namespace."
-        " Please update your query to reference this function as 'nokogiri:%s'."
-        " Invoking custom handler functions without a namespace is deprecated and support will be removed in a future release of Nokogiri.",
-        c_name, c_name);
+      NOKO_WARN_DEPRECATION("A custom XPath or CSS handler function named '%s' is being invoked without a namespace. Please update your query to reference this function as 'nokogiri:%s'. Invoking custom handler functions without a namespace is deprecated and will become an error in Nokogiri v1.17.0.",
+                            c_name, c_name); // deprecated in v1.15.0, remove in v1.17.0
     }
     return method_caller;
   }

data/ext/nokogiri/xslt_stylesheet.c

@@ -71,7 +71,12 @@ Nokogiri_wrap_xslt_stylesheet(xsltStylesheetPtr ss)
  * call-seq:
  *   parse_stylesheet_doc(document)
  *
- * Parse a stylesheet from +document+.
+ * Parse an XSLT::Stylesheet from +document+.
+ *
+ * [Parameters]
+ * - +document+ (Nokogiri::XML::Document) the document to be parsed.
+ *
+ * [Returns] Nokogiri::XSLT::Stylesheet
  */
 static VALUE
 parse_stylesheet_doc(VALUE klass, VALUE xmldocobj)
@@ -104,7 +109,7 @@ parse_stylesheet_doc(VALUE klass, VALUE xmldocobj)
  * call-seq:
  *   serialize(document)
  *
- * Serialize +document+ to an xml string.
+ * Serialize +document+ to an xml string, as specified by the +method+ parameter in the Stylesheet.
  */
 static VALUE
 rb_xslt_stylesheet_serialize(VALUE self, VALUE xmlobj)
@@ -133,7 +138,7 @@ rb_xslt_stylesheet_serialize(VALUE self, VALUE xmlobj)
  *   transform(document)
  *   transform(document, params = {})
  *
- * Apply an XSLT stylesheet to an XML::Document.
+ * Transform an XML::Document as defined by an XSLT::Stylesheet.
  *
  * [Parameters]
  * - +document+ (Nokogiri::XML::Document) the document to be transformed.

data/gumbo-parser/Makefile

@@ -13,6 +13,23 @@ LDFLAGS := -pthread
 
 all: check
 
+oss-fuzz:
+	./fuzzer/build-ossfuzz.sh
+
+fuzzers: fuzzer-normal fuzzer-asan fuzzer-ubsan fuzzer-msan
+
+fuzzer-normal:
+	./fuzzer/build.sh
+
+fuzzer-asan:
+	SANITIZER=asan ./fuzzer/build.sh
+
+fuzzer-ubsan:
+	SANITIZER=ubsan ./fuzzer/build.sh
+
+fuzzer-msan:
+	SANITIZER=msan ./fuzzer/build.sh
+
 # don't try to regenerate ragel or gperf files in CI, that should be a development-only action and
 # the generated files should be committed to SCM
 ifneq ($(CI),true)
@@ -81,6 +98,7 @@ coverage:
 
 clean:
 	$(RM) -r build
+	$(RM) -r fuzzer/build fuzzer/src-* fuzzer/gumbo_corpus
 
 build/src/flags: | build/src
 	@echo 'old_CC := $(CC)' > $@

data/gumbo-parser/src/error.c

@@ -357,7 +357,7 @@ static void handle_parser_error (
       print_tag_stack(error, output);
       return;
     case GUMBO_TOKEN_END_TAG:
-      print_message(output, "Eng tag '%s' isn't allowed here.",
+      print_message(output, "End tag '%s' isn't allowed here.",
                     gumbo_normalized_tagname(error->input_tag));
       print_tag_stack(error, output);
       return;

data/gumbo-parser/src/parser.c

@@ -4826,14 +4826,17 @@ GumboOutput* gumbo_parse_with_options (
       // to a token.
       if (token.type == GUMBO_TOKEN_END_TAG &&
           token.v.end_tag.tag == GUMBO_TAG_UNKNOWN)
+      {
         gumbo_free(token.v.end_tag.name);
+        token.v.end_tag.name = NULL;
+      }
+      if (unlikely(state->_open_elements.length > max_tree_depth)) {
+        parser._output->status = GUMBO_STATUS_TREE_TOO_DEEP;
+        gumbo_debug("Tree depth limit exceeded.\n");
+        break;
+      }
     }
 
-    if (unlikely(state->_open_elements.length > max_tree_depth)) {
-      parser._output->status = GUMBO_STATUS_TREE_TOO_DEEP;
-      gumbo_debug("Tree depth limit exceeded.\n");
-      break;
-    }
 
     ++loop_count;
     assert(loop_count < 1000000000UL);

data/gumbo-parser/src/tokenizer.c

@@ -506,6 +506,7 @@ static void abandon_current_tag(GumboParser* parser) {
   for (unsigned int i = 0; i < tag_state->_attributes.length; ++i) {
     gumbo_destroy_attribute(tag_state->_attributes.data[i]);
   }
+  gumbo_free(tag_state->_name);
   gumbo_free(tag_state->_attributes.data);
   mark_tag_state_as_empty(tag_state);
   gumbo_string_buffer_destroy(&tag_state->_buffer);

data/lib/nokogiri/css/parser_extras.rb

@@ -23,7 +23,7 @@ module Nokogiri
 
         # Get the css selector in +string+ from the cache
         def [](string)
-          return nil unless cache_on?
+          return unless cache_on?
 
           @mutex.synchronize { @cache[string] }
         end

data/lib/nokogiri/css/xpath_visitor.rb

@@ -302,7 +302,7 @@ module Nokogiri
       end
 
       def read_a_and_positive_b(values)
-        op = values[2]
+        op = values[2].strip
         if op == "+"
           a = values[0].to_i
           b = values[3].to_i
@@ -335,25 +335,5 @@ module Nokogiri
         end
       end
     end
-
-    module XPathVisitorAlwaysUseBuiltins # :nodoc:
-      def self.new
-        warn(
-          "Nokogiri::CSS::XPathVisitorAlwaysUseBuiltins is deprecated and will be removed in a future version of Nokogiri",
-          { uplevel: 1 },
-        )
-        XPathVisitor.new(builtins: :always)
-      end
-    end
-
-    module XPathVisitorOptimallyUseBuiltins # :nodoc:
-      def self.new
-        warn(
-          "Nokogiri::CSS::XPathVisitorOptimallyUseBuiltins is deprecated and will be removed in a future version of Nokogiri",
-          { uplevel: 1 },
-        )
-        XPathVisitor.new(builtins: :optimal)
-      end
-    end
   end
 end

data/lib/nokogiri/html4/document.rb

@@ -92,7 +92,7 @@ module Nokogiri
         title = XML::Node.new("title", self) << tnode
         if (head = at_xpath("//head"))
           head << title
-        elsif (meta = (at_xpath("//meta[@charset]") || meta_content_type))
+        elsif (meta = at_xpath("//meta[@charset]") || meta_content_type)
           # better put after charset declaration
           meta.add_next_sibling(title)
         else

data/lib/nokogiri/html4/encoding_reader.rb

@@ -94,7 +94,7 @@ module Nokogiri
         # no support for a call without len
 
         unless @firstchunk
-          (@firstchunk = @io.read(len)) || (return nil)
+          (@firstchunk = @io.read(len)) || return
 
           # This implementation expects that the first call from
           # htmlReadIO() is made with a length long enough (~1KB) to

data/lib/nokogiri/html5.rb

@@ -239,23 +239,6 @@ module Nokogiri
         DocumentFragment.parse(string, encoding, options)
       end
 
-      # Fetch and parse a HTML document from the web, following redirects,
-      # handling https, and determining the character encoding using HTML5
-      # rules.  +uri+ may be a +String+ or a +URI+.  +options+ contains
-      # http headers and special options.  Everything which is not a
-      # special option is considered a header.  Special options include:
-      #  * :follow_limit => number of redirects which are followed
-      #  * :basic_auth => [username, password]
-      def get(uri, options = {})
-        # TODO: deprecate
-        warn(
-          "Nokogiri::HTML5.get is deprecated and will be removed in a future version of Nokogiri.",
-          uplevel: 1,
-          category: :deprecated,
-        )
-        get_impl(uri, options)
-      end
-
       # :nodoc:
       def read_and_encode(string, encoding)
         # Read the string with the given encoding.
@@ -283,55 +266,6 @@ module Nokogiri
 
       private
 
-      def get_impl(uri, options = {})
-        headers = options.clone
-        headers = { follow_limit: headers } if Numeric === headers # deprecated
-        limit = headers[:follow_limit] ? headers.delete(:follow_limit).to_i : 10
-
-        require "net/http"
-        uri = URI(uri) unless URI === uri
-
-        http = Net::HTTP.new(uri.host, uri.port)
-
-        # TLS / SSL support
-        http.use_ssl = true if uri.scheme == "https"
-
-        # Pass through Net::HTTP override values, which currently include:
-        #   :ca_file, :ca_path, :cert, :cert_store, :ciphers,
-        #   :close_on_empty_response, :continue_timeout, :key, :open_timeout,
-        #   :read_timeout, :ssl_timeout, :ssl_version, :use_ssl,
-        #   :verify_callback, :verify_depth, :verify_mode
-        options.each do |key, _value|
-          http.send("#{key}=", headers.delete(key)) if http.respond_to?("#{key}=")
-        end
-
-        request = Net::HTTP::Get.new(uri.request_uri)
-
-        # basic authentication
-        auth = headers.delete(:basic_auth)
-        auth ||= [uri.user, uri.password] if uri.user && uri.password
-        request.basic_auth(auth.first, auth.last) if auth
-
-        # remaining options are treated as headers
-        headers.each { |key, value| request[key.to_s] = value.to_s }
-
-        response = http.request(request)
-
-        case response
-        when Net::HTTPSuccess
-          doc = parse(reencode(response.body, response["content-type"]), options)
-          doc.instance_variable_set(:@response, response)
-          doc.class.send(:attr_reader, :response)
-          doc
-        when Net::HTTPRedirection
-          response.value if limit <= 1
-          location = URI.join(uri, response["location"])
-          get_impl(location, options.merge(follow_limit: limit - 1))
-        else
-          response.value
-        end
-      end
-
       # Charset sniffing is a complex and controversial topic that understandably isn't done _by
       # default_ by the Ruby Net::HTTP library.  This being said, it is a very real problem for
       # consumers of HTML as the default for HTML is iso-8859-1, most "good" producers use utf-8, and

data/lib/nokogiri/jruby/nokogiri_jars.rb

@@ -6,10 +6,10 @@ rescue LoadError
   require 'net/sourceforge/htmlunit/neko-htmlunit/2.63.0/neko-htmlunit-2.63.0.jar'
   require 'nu/validator/jing/20200702VNU/jing-20200702VNU.jar'
   require 'xerces/xercesImpl/2.12.2/xercesImpl-2.12.2.jar'
-  require 'org/nokogiri/nekodtd/0.1.11.noko1/nekodtd-0.1.11.noko1.jar'
   require 'net/sf/saxon/Saxon-HE/9.6.0-4/Saxon-HE-9.6.0-4.jar'
   require 'xalan/xalan/2.7.3/xalan-2.7.3.jar'
   require 'xml-apis/xml-apis/1.4.01/xml-apis-1.4.01.jar'
+  require 'org/nokogiri/nekodtd/0.1.11.noko2/nekodtd-0.1.11.noko2.jar'
   require 'isorelax/isorelax/20030108/isorelax-20030108.jar'
 end
 
@@ -18,10 +18,10 @@ if defined? Jars
   require_jar 'net.sourceforge.htmlunit', 'neko-htmlunit', '2.63.0'
   require_jar 'nu.validator', 'jing', '20200702VNU'
   require_jar 'xerces', 'xercesImpl', '2.12.2'
-  require_jar 'org.nokogiri', 'nekodtd', '0.1.11.noko1'
   require_jar 'net.sf.saxon', 'Saxon-HE', '9.6.0-4'
   require_jar 'xalan', 'xalan', '2.7.3'
   require_jar 'xml-apis', 'xml-apis', '1.4.01'
+  require_jar 'org.nokogiri', 'nekodtd', '0.1.11.noko2'
   require_jar 'isorelax', 'isorelax', '20030108'
 end
 
@@ -32,7 +32,7 @@ module Nokogiri
     "net.sf.saxon:Saxon-HE" => "9.6.0-4",
     "net.sourceforge.htmlunit:neko-htmlunit" => "2.63.0",
     "nu.validator:jing" => "20200702VNU",
-    "org.nokogiri:nekodtd" => "0.1.11.noko1",
+    "org.nokogiri:nekodtd" => "0.1.11.noko2",
     "xalan:serializer" => "2.7.3",
     "xalan:xalan" => "2.7.3",
     "xerces:xercesImpl" => "2.12.2",

data/lib/nokogiri/version/constant.rb

@@ -2,5 +2,5 @@
 
 module Nokogiri
   # The version of Nokogiri you are using
-  VERSION = "1.15.1"
+  VERSION = "1.16.5"
 end

data/lib/nokogiri/version/info.rb

@@ -94,11 +94,14 @@ module Nokogiri
           nokogiri["version"] = Nokogiri::VERSION
 
           unless jruby?
-            #  enable gems like nokogumbo to build with the following in their extconf.rb:
+            #  enable gems to build against Nokogiri with the following in their extconf.rb:
             #
             #    append_cflags(Nokogiri::VERSION_INFO["nokogiri"]["cppflags"])
             #    append_ldflags(Nokogiri::VERSION_INFO["nokogiri"]["ldflags"])
             #
+            #  though, this won't work on all platform and versions of Ruby, and won't be supported
+            #  forever, see https://github.com/sparklemotion/nokogiri/discussions/2746 for context.
+            #
             cppflags = ["-I#{header_directory.shellescape}"]
             ldflags = []
 
@@ -108,7 +111,8 @@ module Nokogiri
             end
 
             if windows?
-              # on windows, nokogumbo needs to link against nokogiri.so to resolve symbols. see #2167
+              # on windows, third party libraries that wish to link against nokogiri
+              # should link against nokogiri.so to resolve symbols. see #2167
               lib_directory = File.expand_path(File.join(File.dirname(__FILE__), "../#{ruby_minor}"))
               unless File.exist?(lib_directory)
                 lib_directory = File.expand_path(File.join(File.dirname(__FILE__), ".."))
@@ -136,9 +140,6 @@ module Nokogiri
               libxml["source"] = "packaged"
               libxml["precompiled"] = libxml2_precompiled?
               libxml["patches"] = Nokogiri::LIBXML2_PATCHES
-
-              # this is for nokogumbo and shouldn't be forever
-              libxml["libxml2_path"] = header_directory
             else
               libxml["source"] = "system"
             end

data/lib/nokogiri/xml/attr.rb

@@ -18,8 +18,6 @@ module Nokogiri
       #  - +value+ → (String) The value of the attribute.
       #  - +namespace+ → (Namespace, nil) The Namespace of the attribute, or +nil+ if there is no namespace.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -52,6 +50,8 @@ module Nokogiri
       #    #        href = "http://nokogiri.org/ns/noko"
       #    #        })}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { name: name, value: value, namespace: namespace }
       end

data/lib/nokogiri/xml/document.rb

@@ -174,8 +174,7 @@ module Nokogiri
       # Since v1.12.4
       attr_accessor :namespace_inheritance
 
-      # :nodoc:
-      def initialize(*args) # rubocop:disable Lint/MissingSuper
+      def initialize(*args) # :nodoc: # rubocop:disable Lint/MissingSuper
         @errors     = []
         @decorators = nil
         @namespace_inheritance = false
@@ -330,7 +329,7 @@ module Nokogiri
       # Validate this Document against it's DTD.  Returns a list of errors on
       # the document or +nil+ when there is no DTD.
       def validate
-        return nil unless internal_subset
+        return unless internal_subset
 
         internal_subset.validate(self)
       end
@@ -427,8 +426,6 @@ module Nokogiri
       #  instructions. If you have a use case and would like this functionality, please let us know
       #  by opening an issue or a discussion on the github project.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -455,6 +452,8 @@ module Nokogiri
       #    doc.deconstruct_keys([:root])
       #    # => {:root=>nil}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { root: root }
       end

data/lib/nokogiri/xml/document_fragment.rb

@@ -154,8 +154,6 @@ module Nokogiri
       #  root elements, you should deconstruct the array returned by
       #  <tt>DocumentFragment#elements</tt>.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    frag = Nokogiri::HTML5.fragment(<<~HTML)
@@ -187,6 +185,8 @@ module Nokogiri
       #    #       }),
       #    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] })]
       #
+      #  Since v1.14.0
+      #
       def deconstruct
         children.to_a
       end

data/lib/nokogiri/xml/namespace.rb

@@ -16,8 +16,6 @@ module Nokogiri
       #  - +prefix+ → (String, nil) The namespace's prefix, or +nil+ if there is no prefix (e.g., default namespace).
       #  - +href+ → (String) The namespace's URI
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -43,6 +41,7 @@ module Nokogiri
       #    doc.root.elements.last.namespace.deconstruct_keys([:prefix, :href])
       #    # => {:prefix=>"noko", :href=>"http://nokogiri.org/ns/noko"}
       #
+      #  Since v1.14.0
       #
       def deconstruct_keys(keys)
         { prefix: prefix, href: href }

data/lib/nokogiri/xml/node.rb

@@ -1049,29 +1049,35 @@ module Nokogiri
 
         return Nokogiri::XML::NodeSet.new(document) if contents.empty?
 
-        # libxml2 does not obey the +recover+ option after encountering errors during +in_context+
-        # parsing, and so this horrible hack is here to try to emulate recovery behavior.
-        #
-        # Unfortunately, this means we're no longer parsing "in context" and so namespaces that
-        # would have been inherited from the context node won't be handled correctly. This hack was
-        # written in 2010, and I regret it, because it's silently degrading functionality in a way
-        # that's not easily prevented (or even detected).
-        #
-        # I think preferable behavior would be to either:
-        #
-        # a. add an error noting that we "fell back" and pointing the user to turning off the +recover+ option
-        # b. don't recover, but raise a sensible exception
-        #
-        # For context and background: https://github.com/sparklemotion/nokogiri/issues/313
-        # FIXME bug report: https://github.com/sparklemotion/nokogiri/issues/2092
         error_count = document.errors.length
         node_set = in_context(contents, options.to_i)
-        if node_set.empty? && (document.errors.length > error_count)
-          if options.recover?
+        if document.errors.length > error_count
+          raise document.errors[error_count] unless options.recover?
+
+          if node_set.empty?
+            # libxml2 < 2.13 does not obey the +recover+ option after encountering errors during
+            # +in_context+ parsing, and so this horrible hack is here to try to emulate recovery
+            # behavior.
+            #
+            # (Note that HTML4 fragment parsing seems to have been fixed in abd74186, and XML
+            # fragment parsing is fixed in 1c106edf. Both are in 2.13.)
+            #
+            # Unfortunately, this means we're no longer parsing "in context" and so namespaces that
+            # would have been inherited from the context node won't be handled correctly. This hack
+            # was written in 2010, and I regret it, because it's silently degrading functionality in
+            # a way that's not easily prevented (or even detected).
+            #
+            # I think preferable behavior would be to either:
+            #
+            # a. add an error noting that we "fell back" and pointing the user to turning off the
+            #    +recover+ option
+            # b. don't recover, but raise a sensible exception
+            #
+            # For context and background:
+            # - https://github.com/sparklemotion/nokogiri/issues/313
+            # - https://github.com/sparklemotion/nokogiri/issues/2092
             fragment = document.related_class("DocumentFragment").parse(contents)
             node_set = fragment.children
-          else
-            raise document.errors[error_count]
           end
         end
         node_set
@@ -1165,7 +1171,7 @@ module Nokogiri
       # Fetch the Nokogiri::HTML4::ElementDescription for this node.  Returns
       # nil on XML documents and on unknown tags.
       def description
-        return nil if document.xml?
+        return if document.xml?
 
         Nokogiri::HTML4::ElementDescription[name]
       end
@@ -1254,8 +1260,8 @@ module Nokogiri
       # Compare two Node objects with respect to their Document.  Nodes from
       # different documents cannot be compared.
       def <=>(other)
-        return nil unless other.is_a?(Nokogiri::XML::Node)
-        return nil unless document == other.document
+        return unless other.is_a?(Nokogiri::XML::Node)
+        return unless document == other.document
 
         compare(other)
       end
@@ -1278,6 +1284,7 @@ module Nokogiri
       #   end
       #
       def serialize(*args, &block)
+        # TODO: deprecate non-hash options, see 46c68ed 2009-06-20 for context
         options = if args.first.is_a?(Hash)
           args.shift
         else
@@ -1429,8 +1436,6 @@ module Nokogiri
       #  - +content+ → (String) The contents of all the text nodes in this node's subtree. See #content.
       #  - +inner_html+ → (String) The inner markup for the children of this node. See #inner_html.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -1465,6 +1470,8 @@ module Nokogiri
       #    #         value = "def"
       #    #         })]}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         requested_keys = DECONSTRUCT_KEYS & keys
         {}.tap do |values|

data/lib/nokogiri/xml/node_set.rb

@@ -372,7 +372,7 @@ module Nokogiri
       # Removes the last element from set and returns it, or +nil+ if
       # the set is empty
       def pop
-        return nil if length == 0
+        return if length == 0
 
         delete(last)
       end
@@ -381,7 +381,7 @@ module Nokogiri
       # Returns the first element of the NodeSet and removes it.  Returns
       # +nil+ if the set is empty.
       def shift
-        return nil if length == 0
+        return if length == 0
 
         delete(first)
       end
@@ -435,7 +435,7 @@ module Nokogiri
       #
       #  Returns the members of this NodeSet as an array, to use in pattern matching.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
+      #  Since v1.14.0
       #
       def deconstruct
         to_a

data/lib/nokogiri/xml/reader.rb

@@ -3,9 +3,11 @@
 module Nokogiri
   module XML
     ###
-    # Nokogiri::XML::Reader parses an XML document similar to the way a cursor
-    # would move.  The Reader is given an XML document, and yields nodes
-    # to an each block.
+    # Nokogiri::XML::Reader parses an XML document similar to the way a cursor would move. The
+    # Reader is given an XML document, and yields nodes to an each block.
+    #
+    # The Reader parser might be good for when you need the speed and low memory usage of the SAX
+    # parser, but do not want to write a Document handler.
     #
     # Here is an example of usage:
     #
@@ -22,13 +24,12 @@ module Nokogiri
     #
     #     end
     #
-    # Note that Nokogiri::XML::Reader#each can only be called once!!  Once
-    # the cursor moves through the entire document, you must parse the
-    # document again.  So make sure that you capture any information you
-    # need during the first iteration.
+    # ⚠ Nokogiri::XML::Reader#each can only be called once! Once the cursor moves through the entire
+    # document, you must parse the document again. It may be better to capture all information you
+    # need during a single iteration.
     #
-    # The Reader parser is good for when you need the speed of a SAX parser,
-    # but do not want to write a Document handler.
+    # ⚠ libxml2 does not support error recovery in the Reader parser. The `RECOVER` ParseOption is
+    # ignored. If a syntax error is encountered during parsing, an exception will be raised.
     class Reader
       include Enumerable