doc: clarify Node#inner_html= behavior

because it's not always parsed as HTML. Closes #2655 [skip ci]
sparklemotion · Oct 7, 2022 · cdbdd82 · cdbdd82
1 parent a46a067
commit cdbdd82
Showing 1 changed file with 55 additions and 19 deletions.
diff --git a/lib/nokogiri/xml/node.rb b/lib/nokogiri/xml/node.rb
@@ -137,9 +137,12 @@ def decorate!
 
       ###
       # Add +node_or_tags+ as a child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +<<+.
       def add_child(node_or_tags)
@@ -154,9 +157,12 @@ def add_child(node_or_tags)
 
       ###
       # Add +node_or_tags+ as the first child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +add_child+.
       def prepend_child(node_or_tags)
@@ -183,7 +189,9 @@ def wrap(html)
 
       ###
       # Add +node_or_tags+ as a child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
       #
       # Returns self, to support chaining of calls (e.g., root << child1 << child2)
       #
@@ -195,9 +203,12 @@ def <<(node_or_tags)
 
       ###
       # Insert +node_or_tags+ before this Node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +before+.
       def add_previous_sibling(node_or_tags)
@@ -209,9 +220,12 @@ def add_previous_sibling(node_or_tags)
 
       ###
       # Insert +node_or_tags+ after this Node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +after+.
       def add_next_sibling(node_or_tags)
@@ -223,7 +237,9 @@ def add_next_sibling(node_or_tags)
 
       ####
       # Insert +node_or_tags+ before this node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
       #
       # Returns self, to support chaining of calls.
       #
@@ -235,7 +251,9 @@ def before(node_or_tags)
 
       ####
       # Insert +node_or_tags+ after this node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
       #
       # Returns self, to support chaining of calls.
       #
@@ -246,17 +264,29 @@ def after(node_or_tags)
       end
 
       ####
-      # Set the inner html for this Node to +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      # Set the content for this Node to +node_or_tags+.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
+      #
+      # ⚠ Please note that despite the name, this method will *not* always parse a String argument
+      # as HTML. A String argument will be parsed with the +DocumentFragment+ parser related to this
+      # node's document.
+      #
+      # For example, if the document is an HTML4::Document then the string will be parsed as HTML4
+      # using HTML4::DocumentFragment; but if the document is an XML::Document then it will
+      # parse the string as XML using XML::DocumentFragment.
       #
       # Also see related method +children=+
       def inner_html=(node_or_tags)
         self.children = node_or_tags
       end
 
       ####
-      # Set the inner html for this Node +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      # Set the content for this Node +node_or_tags+
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
       #
       # Also see related method +inner_html=+
       def children=(node_or_tags)
@@ -271,9 +301,12 @@ def children=(node_or_tags)
 
       ####
       # Replace this Node with +node_or_tags+.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +swap+.
       def replace(node_or_tags)
@@ -303,7 +336,9 @@ def replace(node_or_tags)
 
       ####
       # Swap this Node for +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # Containing markup.
       #
       # Returns self, to support chaining of calls.
       #
@@ -314,7 +349,8 @@ def swap(node_or_tags)
       end
 
       ####
-      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not interpreted as markup.
+      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not
+      # interpreted as markup.
       def content=(string)
         self.native_content = encode_special_chars(string.to_s)
       end