nokogiri 1.15.4 → 1.17.2

data/lib/nokogiri/xml/builder.rb

@@ -475,7 +475,14 @@ module Nokogiri
           if block
             old_parent = @doc_builder.parent
             @doc_builder.parent = @node
-            value = @doc_builder.instance_eval(&block)
+
+            arity = @doc_builder.arity || block.arity
+            value = if arity <= 0
+              @doc_builder.instance_eval(&block)
+            else
+              yield(@doc_builder)
+            end
+
             @doc_builder.parent = old_parent
             return value
           end

data/lib/nokogiri/xml/document.rb

@@ -5,12 +5,12 @@ require "pathname"
 
 module Nokogiri
   module XML
-    # Nokogiri::XML::Document is the main entry point for dealing with XML documents.  The Document
-    # is created by parsing an XML document.  See Nokogiri::XML::Document.parse for more information
-    # on parsing.
+    # Nokogiri::XML::Document is the main entry point for dealing with \XML documents. The Document
+    # is created by parsing \XML content from a String or an IO object. See
+    # Nokogiri::XML::Document.parse for more information on parsing.
     #
-    # For searching a Document, see Nokogiri::XML::Searchable#css and
-    # Nokogiri::XML::Searchable#xpath
+    # Document inherits a great deal of functionality from its superclass Nokogiri::XML::Node, so
+    # please read that class's documentation as well.
     class Document < Nokogiri::XML::Node
       # See http://www.w3.org/TR/REC-xml-names/#ns-decl for more details. Note that we're not
       # attempting to handle unicode characters partly because libxml2 doesn't handle unicode
@@ -19,33 +19,45 @@ module Nokogiri
       NCNAME_CHAR       = NCNAME_START_CHAR + "\\-\\.0-9"
       NCNAME_RE         = /^xmlns(?::([#{NCNAME_START_CHAR}][#{NCNAME_CHAR}]*))?$/
 
+      OBJECT_DUP_METHOD = Object.instance_method(:dup)
+      OBJECT_CLONE_METHOD = Object.instance_method(:clone)
+      private_constant :OBJECT_DUP_METHOD, :OBJECT_CLONE_METHOD
+
       class << self
-        # Parse an XML file.
+        # call-seq:
+        #   parse(input) { |options| ... } => Nokogiri::XML::Document
+        #   parse(input, url:, encoding:, options:) => Nokogiri::XML::Document
         #
-        # +string_or_io+ may be a String, or any object that responds to
-        # _read_ and _close_ such as an IO, or StringIO.
+        # Parse \XML input from a String or IO object, and return a new XML::Document.
         #
-        # +url+ (optional) is the URI where this document is located.
+        # 🛡 By default, Nokogiri treats documents as untrusted, and so does not attempt to load DTDs
+        # or access the network. See Nokogiri::XML::ParseOptions for a complete list of options; and
+        # that module's DEFAULT_XML constant for what's set (and not set) by default.
         #
-        # +encoding+ (optional) is the encoding that should be used when processing
-        # the document.
+        # [Required Parameters]
+        # - +input+ (String | IO) The content to be parsed.
         #
-        # +options+ (optional) is a configuration object that sets options during
-        # parsing, such as Nokogiri::XML::ParseOptions::RECOVER. See the
-        # Nokogiri::XML::ParseOptions for more information.
+        # [Optional Keyword Arguments]
+        # - +url:+ (String) The base URI for this document.
         #
-        # +block+ (optional) is passed a configuration object on which
-        # parse options may be set.
+        # - +encoding:+ (String) The name of the encoding that should be used when processing the
+        #   document. When not provided, the encoding will be determined based on the document
+        #   content.
         #
-        # By default, Nokogiri treats documents as untrusted, and so
-        # does not attempt to load DTDs or access the network. See
-        # Nokogiri::XML::ParseOptions for a complete list of options;
-        # and that module's DEFAULT_XML constant for what's set (and not
-        # set) by default.
+        # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+        #   behaviors during parsing. See ParseOptions for more information. The default value is
+        #   +ParseOptions::DEFAULT_XML+.
         #
-        # Nokogiri.XML() is a convenience method which will call this method.
+        # [Yields]
+        #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+        #   can be configured before parsing. See Nokogiri::XML::ParseOptions for more information.
         #
-        def parse(string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML)
+        # [Returns] Nokogiri::XML::Document
+        def parse(
+          string_or_io,
+          url_ = nil, encoding_ = nil, options_ = XML::ParseOptions::DEFAULT_XML,
+          url: url_, encoding: encoding_, options: options_
+        )
           options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
           yield options if block_given?
 
@@ -60,6 +72,7 @@ module Nokogiri
           end
 
           doc = if string_or_io.respond_to?(:read)
+            # TODO: should we instead check for respond_to?(:to_path) ?
             if string_or_io.is_a?(Pathname)
               # resolve the Pathname to the file and open it as an IO object, see #2110
               string_or_io = string_or_io.expand_path.open
@@ -174,13 +187,44 @@ 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
       end
 
+      #
+      # :call-seq:
+      #   dup → Nokogiri::XML::Document
+      #   dup(level) → Nokogiri::XML::Document
+      #
+      # Duplicate this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # [Returns] The new Nokogiri::XML::Document
+      #
+      def dup(level = 1)
+        copy = OBJECT_DUP_METHOD.bind_call(self)
+        copy.initialize_copy_with_args(self, level)
+      end
+
+      #
+      # :call-seq:
+      #   clone → Nokogiri::XML::Document
+      #   clone(level) → Nokogiri::XML::Document
+      #
+      # Clone this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # [Returns] The new Nokogiri::XML::Document
+      #
+      def clone(level = 1)
+        copy = OBJECT_CLONE_METHOD.bind_call(self)
+        copy.initialize_copy_with_args(self, level)
+      end
+
       # :call-seq:
       #   create_element(name, *contents_or_attrs, &block) → Nokogiri::XML::Element
       #
@@ -327,10 +371,10 @@ module Nokogiri
       end
 
       ##
-      # Validate this Document against it's DTD.  Returns a list of errors on
+      # Validate this Document against its 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
@@ -368,12 +412,11 @@ module Nokogiri
         @decorators.each do |klass, list|
           next unless node.is_a?(klass)
 
-          list.each { |moodule| node.extend(moodule) }
+          list.each { |mod| node.extend(mod) }
         end
       end
 
       alias_method :to_xml, :serialize
-      alias_method :clone, :dup
 
       # Get the hash of namespaces on the root Nokogiri::XML::Node
       def namespaces
@@ -427,8 +470,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 +496,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

@@ -3,32 +3,103 @@
 
 module Nokogiri
   module XML
+    # DocumentFragment represents a fragment of an \XML document. It provides the same functionality
+    # exposed by XML::Node and can be used to contain one or more \XML subtrees.
     class DocumentFragment < Nokogiri::XML::Node
-      ####
-      # Create a Nokogiri::XML::DocumentFragment from +tags+
-      def self.parse(tags, options = ParseOptions::DEFAULT_XML, &block)
-        new(XML::Document.new, tags, nil, options, &block)
+      # The options used to parse the document fragment. Returns the value of any options that were
+      # passed into the constructor as a parameter or set in a config block, else the default
+      # options for the specific subclass.
+      attr_reader :parse_options
+
+      class << self
+        # :call-seq:
+        #   parse(input) { |options| ... } → XML::DocumentFragment
+        #   parse(input, options:) → XML::DocumentFragment
+        #
+        # Parse \XML fragment input from a String, and return a new XML::DocumentFragment. This
+        # method creates a new, empty XML::Document to contain the fragment.
+        #
+        # [Required Parameters]
+        # - +input+ (String) The content to be parsed.
+        #
+        # [Optional Keyword Arguments]
+        # - +options+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+        #   behaviors during parsing. See ParseOptions for more information. The default value is
+        #   +ParseOptions::DEFAULT_XML+.
+        #
+        # [Yields]
+        #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+        #   can be configured before parsing. See Nokogiri::XML::ParseOptions for more information.
+        #
+        # [Returns] Nokogiri::XML::DocumentFragment
+        def parse(tags, options_ = ParseOptions::DEFAULT_XML, options: options_, &block)
+          new(XML::Document.new, tags, options: options, &block)
+        end
+
+        # Wrapper method to separate the concerns of:
+        # - the native object allocator's parameter (it only requires `document`)
+        # - the initializer's parameters
+        def new(document, ...) # :nodoc:
+          instance = native_new(document)
+          instance.send(:initialize, document, ...)
+          instance
+        end
       end
 
-      ##
-      #  Create a new DocumentFragment from +tags+.
+      # :call-seq:
+      #   new(document, input=nil) { |options| ... } → DocumentFragment
+      #   new(document, input=nil, context:, options:) → DocumentFragment
+      #
+      # Parse \XML fragment input from a String, and return a new DocumentFragment that is
+      # associated with the given +document+.
+      #
+      # 💡 It's recommended to use either XML::DocumentFragment.parse or Node#parse rather than call
+      # this method directly.
+      #
+      # [Required Parameters]
+      # - +document+ (XML::Document) The parent document to associate the returned fragment with.
+      #
+      # [Optional Parameters]
+      # - +input+ (String) The content to be parsed.
       #
-      #  If +ctx+ is present, it is used as a context node for the
-      #  subtree created, e.g., namespaces will be resolved relative
-      #  to +ctx+.
-      def initialize(document, tags = nil, ctx = nil, options = ParseOptions::DEFAULT_XML) # rubocop:disable Lint/MissingSuper
+      # [Optional Keyword Arguments]
+      # - +context:+ (Nokogiri::XML::Node) The <b>context node</b> for the subtree created. See
+      #   below for more information.
+      #
+      # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+      #   behaviors during parsing. See ParseOptions for more information. The default value is
+      #   +ParseOptions::DEFAULT_XML+.
+      #
+      # [Yields]
+      #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+      #   can be configured before parsing. See ParseOptions for more information.
+      #
+      # [Returns] XML::DocumentFragment
+      #
+      # === Context \Node
+      #
+      # If a context node is specified using +context:+, then the fragment will be created by
+      # calling Node#parse on that node, so the parser will behave as if that Node is the parent of
+      # the fragment subtree, and will resolve namespaces relative to that node.
+      #
+      def initialize(
+        document, tags = nil,
+        context_ = nil, options_ = ParseOptions::DEFAULT_XML,
+        context: context_, options: options_
+      ) # rubocop:disable Lint/MissingSuper
         return self unless tags
 
         options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        @parse_options = options
         yield options if block_given?
 
-        children = if ctx
+        children = if context
           # Fix for issue#490
           if Nokogiri.jruby?
             # fix for issue #770
-            ctx.parse("<root #{namespace_declarations(ctx)}>#{tags}</root>", options).children
+            context.parse("<root #{namespace_declarations(context)}>#{tags}</root>", options).children
           else
-            ctx.parse(tags, options)
+            context.parse(tags, options)
           end
         else
           wrapper_doc = XML::Document.parse("<root>#{tags}</root>", nil, nil, options)
@@ -154,8 +225,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 +256,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

@@ -127,6 +127,42 @@ module Nokogiri
         # This is intentionally empty, and sets the method signature for subclasses.
       end
 
+      #
+      # :call-seq:
+      #   dup → Nokogiri::XML::Node
+      #   dup(level) → Nokogiri::XML::Node
+      #   dup(level, new_parent_doc) → Nokogiri::XML::Node
+      #
+      # Duplicate this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # - +new_parent_doc+ (optional Nokogiri::XML::Document)
+      #   The new node's parent Document. Defaults to the the Document of the current node.
+      # [Returns] The new Nokogiri::XML::Node
+      #
+      def dup(level = 1, new_parent_doc = document)
+        super().initialize_copy_with_args(self, level, new_parent_doc)
+      end
+
+      #
+      # :call-seq:
+      #   clone → Nokogiri::XML::Node
+      #   clone(level) → Nokogiri::XML::Node
+      #   clone(level, new_parent_doc) → Nokogiri::XML::Node
+      #
+      # Clone this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # - +new_parent_doc+
+      #   The new node's parent Document. Defaults to the the Document of the current node.
+      # [Returns] The new Nokogiri::XML::Node
+      #
+      def clone(level = 1, new_parent_doc = document)
+        super().initialize_copy_with_args(self, level, new_parent_doc)
+      end
+
       ###
       # Decorate this node with the decorators set up in this node's Document
       def decorate!
@@ -228,7 +264,7 @@ module Nokogiri
           if new_parent.nil?
             raise "Failed to parse '#{node_or_tags}' in the context of a '#{context_node.name}' element"
           end
-        when XML::Node
+        when Node
           new_parent = node_or_tags.dup
         else
           raise ArgumentError, "Requires a String or Node argument, and cannot accept a #{node_or_tags.class}"
@@ -406,8 +442,48 @@ module Nokogiri
       end
 
       ####
-      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not
-      # interpreted as markup.
+      # call-seq:
+      #   content=(input)
+      #
+      # Set the content of this node to +input+.
+      #
+      # [Parameters]
+      # - +input+ (String) The new content for this node. Input is considered to be raw content, and
+      #   so will be entity-escaped in the final DOM string.
+      #
+      # [Example]
+      # Note how entities are handled:
+      #
+      #   doc = Nokogiri::HTML::Document.parse(<<~HTML)
+      #     <html>
+      #       <body>
+      #         <div id="first">asdf</div>
+      #         <div id="second">asdf</div>
+      #   HTML
+      #
+      #   text_node = doc.at_css("div#first").children.first
+      #   div_node = doc.at_css("div#second")
+      #
+      #   value = "You &amp; Me"
+      #
+      #   text_node.content = value
+      #   div_node.content = value
+      #
+      #   doc.css("div").to_html
+      #   # => "<div id=\"first\">You &amp;amp; Me</div>
+      #   #     <div id=\"second\">You &amp;amp; Me</div>"
+      #
+      # For content that is already entity-escaped, use CGI::unescapeHTML to decode it:
+      #
+      #   text_node.content = CGI::unescapeHTML(value)
+      #   div_node.content = CGI::unescapeHTML(value)
+      #
+      #   doc.css("div").to_html
+      #   # => "<div id=\"first\">You &amp; Me</div>
+      #   #     <div id=\"second\">You &amp; Me</div>"
+      #
+      # See also: #native_content=
+      #
       def content=(string)
         self.native_content = encode_special_chars(string.to_s)
       end
@@ -474,7 +550,6 @@ module Nokogiri
       alias_method :to_str, :content
       alias_method :name, :node_name
       alias_method :type, :node_type
-      alias_method :clone, :dup
       alias_method :elements, :element_children
 
       # :section: Working With Node Attributes
@@ -1049,31 +1124,40 @@ 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?
+
+          # TODO: remove this block when libxml2 < 2.13 is no longer supported
+          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
       end
 
@@ -1165,7 +1249,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 +1338,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 +1362,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 +1514,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 +1548,8 @@ module Nokogiri
       #    #         value = "def"
       #    #         })]}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         requested_keys = DECONSTRUCT_KEYS & keys
         {}.tap do |values|
@@ -1535,19 +1620,12 @@ module Nokogiri
         node_or_tags
       end
 
-      USING_LIBXML_WITH_BROKEN_SERIALIZATION = Nokogiri.uses_libxml?("~> 2.6.0").freeze
-      private_constant :USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
       def to_format(save_option, options)
-        return dump_html if USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
         options[:save_with] = save_option unless options[:save_with]
         serialize(options)
       end
 
       def write_format_to(save_option, io, options)
-        return (io << dump_html) if USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
         options[:save_with] ||= save_option
         write_to(io, options)
       end

data/lib/nokogiri/xml/node_set.rb

@@ -4,9 +4,13 @@
 module Nokogiri
   module XML
     ####
-    # A NodeSet contains a list of Nokogiri::XML::Node objects.  Typically
-    # a NodeSet is return as a result of searching a Document via
-    # Nokogiri::XML::Searchable#css or Nokogiri::XML::Searchable#xpath
+    # A NodeSet is an Enumerable that contains a list of Nokogiri::XML::Node objects.
+    #
+    # Typically a NodeSet is returned as a result of searching a Document via
+    # Nokogiri::XML::Searchable#css or Nokogiri::XML::Searchable#xpath.
+    #
+    # Note that the `#dup` and `#clone` methods perform shallow copies; these methods do not copy
+    # the Nodes contained in the NodeSet (similar to how Array and other Enumerable classes work).
     class NodeSet
       include Nokogiri::XML::Searchable
       include Enumerable
@@ -14,8 +18,6 @@ module Nokogiri
       # The Document this NodeSet is associated with
       attr_accessor :document
 
-      alias_method :clone, :dup
-
       # Create a NodeSet with +document+ defaulting to +list+
       def initialize(document, list = [])
         @document = document
@@ -121,7 +123,7 @@ module Nokogiri
           return self[args.first]
         end
 
-        super(*args)
+        super
       end
       alias_method :%, :at
 
@@ -372,7 +374,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 +383,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
@@ -423,7 +425,7 @@ module Nokogiri
       end
 
       ###
-      # Return a nicely formated string representation
+      # Return a nicely formatted string representation
       def inspect
         "[#{map(&:inspect).join(", ")}]"
       end
@@ -435,7 +437,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/parse_options.rb

@@ -140,7 +140,7 @@ module Nokogiri
 
       # Relax any hardcoded limit from the parser. Off by default.
       #
-      # ⚠ There may be a performance penalty when this option is set.
+      # ⚠ <b>It is UNSAFE to set this option</b> when parsing untrusted documents.
       HUGE        = 1 << 19
 
       # Support line numbers up to <code>long int</code> (default is a <code>short int</code>). On