feat: document official support for the pattern matching API

CHANGELOG.md

@@ -4,6 +4,25 @@ Nokogiri follows [Semantic Versioning](https://semver.org/), please see the [REA
 
 ---
 
+## next / unreleased
+
+### Notable Changes
+
+#### Pattern matching
+
+This version marks _official support_ for the pattern matching API in `XML::Attr`, `XML::Document`, `XML::DocumentFragment`, `XML::Namespace`, `XML::Node`, and `XML::NodeSet` (and their subclasses), originally introduced as an experimental feature in v1.14.0.
+
+Documentation on what can be matched:
+
+* [`XML::Attr#deconstruct_keys`](https://nokogiri.org/rdoc/Nokogiri/XML/Attr.html?h=deconstruct#method-i-deconstruct_keys)
+* [`XML::Document#deconstruct_keys`](https://nokogiri.org/rdoc/Nokogiri/XML/Document.html?h=deconstruct#method-i-deconstruct_keys)
+* [`XML::Namespace#deconstruct_keys`](https://nokogiri.org/rdoc/Nokogiri/XML/Namespace.html?h=deconstruct+namespace#method-i-deconstruct_keys)
+* [`XML::Node#deconstruct_keys`](https://nokogiri.org/rdoc/Nokogiri/XML/Node.html?h=deconstruct#method-i-deconstruct_keys)
+* [`XML::DocumentFragment#deconstruct`](https://nokogiri.org/rdoc/Nokogiri/XML/DocumentFragment.html?h=deconstruct#method-i-deconstruct)
+* [`XML::NodeSet#deconstruct`](https://nokogiri.org/rdoc/Nokogiri/XML/NodeSet.html?h=deconstruct#method-i-deconstruct)
+
+
+
 ## 1.15.4 / 2023-08-11
 
 ### Dependencies

lib/nokogiri/xml/attr.rb

@@ -18,8 +18,6 @@ class Attr < Node
       #  - +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 @@ class Attr < Node
       #    #        href = "http://nokogiri.org/ns/noko"
       #    #        })}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { name: name, value: value, namespace: namespace }
       end

lib/nokogiri/xml/document.rb

@@ -174,8 +174,7 @@ def empty_doc?(string_or_io)
       # 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
@@ -427,8 +426,6 @@ def xpath_doctype
       #  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 @@ def xpath_doctype
       #    doc.deconstruct_keys([:root])
       #    # => {:root=>nil}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { root: root }
       end

lib/nokogiri/xml/document_fragment.rb

@@ -154,8 +154,6 @@ def fragment(data)
       #  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 @@ def fragment(data)
       #    #       }),
       #    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] })]
       #
+      #  Since v1.14.0
+      #
       def deconstruct
         children.to_a
       end

lib/nokogiri/xml/namespace.rb

@@ -16,8 +16,6 @@ class Namespace
       #  - +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 @@ class Namespace
       #    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 }

lib/nokogiri/xml/node.rb

@@ -1430,8 +1430,6 @@ def canonicalize(mode = XML::XML_C14N_1_0, inclusive_namespaces = nil, with_comm
       #  - +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)
@@ -1466,6 +1464,8 @@ def canonicalize(mode = XML::XML_C14N_1_0, inclusive_namespaces = nil, with_comm
       #    #         value = "def"
       #    #         })]}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         requested_keys = DECONSTRUCT_KEYS & keys
         {}.tap do |values|

lib/nokogiri/xml/node_set.rb

@@ -435,7 +435,7 @@ def inspect
       #
       #  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