From fd55ee80e2857581c6355ad5879c302fc577955a Mon Sep 17 00:00:00 2001
From: Jonathan Hedley <jonathan@hedley.net>
Date: Mon, 12 Aug 2024 16:04:19 +1000
Subject: [PATCH] Nullability and other minor code tweaks

---
 src/main/java/org/jsoup/nodes/Attributes.java     |  4 ++--
 src/main/java/org/jsoup/nodes/CDataNode.java      |  4 ++--
 src/main/java/org/jsoup/nodes/Comment.java        |  7 +------
 src/main/java/org/jsoup/nodes/DataNode.java       | 11 +++--------
 src/main/java/org/jsoup/nodes/Document.java       |  7 +++----
 src/main/java/org/jsoup/nodes/Element.java        |  2 +-
 src/main/java/org/jsoup/nodes/FormElement.java    | 11 ++++++-----
 src/main/java/org/jsoup/nodes/LeafNode.java       |  2 +-
 src/main/java/org/jsoup/nodes/Node.java           |  8 ++++----
 src/main/java/org/jsoup/nodes/NodeUtils.java      |  2 +-
 src/main/java/org/jsoup/nodes/Range.java          |  8 +++++++-
 src/main/java/org/jsoup/nodes/TextNode.java       |  2 +-
 src/main/java/org/jsoup/nodes/XmlDeclaration.java |  2 +-
 src/main/java/org/jsoup/parser/Parser.java        |  3 ++-
 14 files changed, 35 insertions(+), 38 deletions(-)

diff --git a/src/main/java/org/jsoup/nodes/Attributes.java b/src/main/java/org/jsoup/nodes/Attributes.java
index 6a3c0b549e..bc0f458795 100644
--- a/src/main/java/org/jsoup/nodes/Attributes.java
+++ b/src/main/java/org/jsoup/nodes/Attributes.java
@@ -119,7 +119,7 @@ public String get(String key) {
      @return the Attribute for this key, or null if not present.
      @since 1.17.2
      */
-    @Nullable Attribute attribute(String key) {
+    @Nullable public Attribute attribute(String key) {
         int i = indexOfKey(key);
         return i == NotFound ? null : new Attribute(key, checkNotNull(vals[i]), this);
     }
@@ -393,7 +393,7 @@ public Range.AttributeRange sourceRange(String key) {
     @Override
     public Iterator<Attribute> iterator() {
         //noinspection ReturnOfInnerClass
-        return new Iterator<>() {
+        return new Iterator<Attribute>() {
             int expectedSize = size;
             int i = 0;
 
diff --git a/src/main/java/org/jsoup/nodes/CDataNode.java b/src/main/java/org/jsoup/nodes/CDataNode.java
index 99e418d8e1..3affd7e586 100644
--- a/src/main/java/org/jsoup/nodes/CDataNode.java
+++ b/src/main/java/org/jsoup/nodes/CDataNode.java
@@ -16,8 +16,8 @@ public String nodeName() {
     }
 
     /**
-     * Get the unencoded, <b>non-normalized</b> text content of this CDataNode.
-     * @return unencoded, non-normalized text
+     * Get the un-encoded, <b>non-normalized</b> text content of this CDataNode.
+     * @return un-encoded, non-normalized text
      */
     @Override
     public String text() {
diff --git a/src/main/java/org/jsoup/nodes/Comment.java b/src/main/java/org/jsoup/nodes/Comment.java
index a3ed2852e1..848d82d69e 100644
--- a/src/main/java/org/jsoup/nodes/Comment.java
+++ b/src/main/java/org/jsoup/nodes/Comment.java
@@ -19,7 +19,7 @@ public Comment(String data) {
         value = data;
     }
 
-    public String nodeName() {
+    @Override public String nodeName() {
         return "#comment";
     }
 
@@ -49,11 +49,6 @@ void outerHtmlHead(Appendable accum, int depth, Document.OutputSettings out) thr
     @Override
     void outerHtmlTail(Appendable accum, int depth, Document.OutputSettings out) {}
 
-    @Override
-    public String toString() {
-        return outerHtml();
-    }
-
     @Override
     public Comment clone() {
         return (Comment) super.clone();
diff --git a/src/main/java/org/jsoup/nodes/DataNode.java b/src/main/java/org/jsoup/nodes/DataNode.java
index 9b5a77d8d1..0580a11ab0 100644
--- a/src/main/java/org/jsoup/nodes/DataNode.java
+++ b/src/main/java/org/jsoup/nodes/DataNode.java
@@ -16,7 +16,7 @@ public DataNode(String data) {
         value = data;
     }
 
-    public String nodeName() {
+    @Override public String nodeName() {
         return "#data";
     }
 
@@ -30,7 +30,7 @@ public String getWholeData() {
 
     /**
      * Set the data contents of this node.
-     * @param data unencoded data
+     * @param data un-encoded data
      * @return this node, for chaining
      */
     public DataNode setWholeData(String data) {
@@ -41,7 +41,7 @@ public DataNode setWholeData(String data) {
     @Override
     void outerHtmlHead(Appendable accum, int depth, Document.OutputSettings out) throws IOException {
         /* For XML output, escape the DataNode in a CData section. The data may contain pseudo-CData content if it was
-        parsed as HTML, so don't double up Cdata. Output in polygot HTML / XHTML / XML format. */
+        parsed as HTML, so don't double up Cdata. Output in polyglot HTML / XHTML / XML format. */
         final String data = getWholeData();
         if (out.syntax() == Document.OutputSettings.Syntax.xml && !data.contains("<![CDATA[")) {
             if (parentNameIs("script"))
@@ -59,11 +59,6 @@ else if (parentNameIs("style"))
     @Override
     void outerHtmlTail(Appendable accum, int depth, Document.OutputSettings out) {}
 
-    @Override
-    public String toString() {
-        return outerHtml();
-    }
-
     @Override
     public DataNode clone() {
         return (DataNode) super.clone();
diff --git a/src/main/java/org/jsoup/nodes/Document.java b/src/main/java/org/jsoup/nodes/Document.java
index 7246f32679..79091902f2 100644
--- a/src/main/java/org/jsoup/nodes/Document.java
+++ b/src/main/java/org/jsoup/nodes/Document.java
@@ -62,7 +62,6 @@ public static Document createShell(String baseUri) {
         Validate.notNull(baseUri);
 
         Document doc = new Document(baseUri);
-        doc.parser = doc.parser();
         Element html = doc.appendElement("html");
         html.appendElement("head");
         html.appendElement("body");
@@ -125,7 +124,7 @@ private Element htmlEl() {
     /**
      Get this document's {@code head} element.
      <p>
-     As a side-effect, if this Document does not already have a HTML structure, it will be created. If you do not want
+     As a side effect, if this Document does not already have an HTML structure, it will be created. If you do not want
      that, use {@code #selectFirst("head")} instead.
 
      @return {@code head} element.
@@ -144,7 +143,7 @@ public Element head() {
     /**
      Get this document's {@code <body>} or {@code <frameset>} element.
      <p>
-     As a <b>side-effect</b>, if this Document does not already have a HTML structure, it will be created with a {@code
+     As a <b>side-effect</b>, if this Document does not already have an HTML structure, it will be created with a {@code
     <body>} element. If you do not want that, use {@code #selectFirst("body")} instead.
 
      @return {@code body} element for documents with a {@code <body>}, a new {@code <body>} element if the document
@@ -229,7 +228,7 @@ public String outerHtml() {
 
     /**
      Set the text of the {@code body} of this document. Any existing nodes within the body will be cleared.
-     @param text unencoded text
+     @param text un-encoded text
      @return this document
      */
     @Override
diff --git a/src/main/java/org/jsoup/nodes/Element.java b/src/main/java/org/jsoup/nodes/Element.java
index b065248ec5..aff327b115 100644
--- a/src/main/java/org/jsoup/nodes/Element.java
+++ b/src/main/java/org/jsoup/nodes/Element.java
@@ -288,7 +288,7 @@ public Element attr(String attributeKey, boolean attributeValue) {
      @return the Attribute for this key, or null if not present.
      @since 1.17.2
      */
-    @Nullable Attribute attribute(String key) {
+    @Nullable public Attribute attribute(String key) {
         return hasAttributes() ? attributes().attribute(key) : null;
     }
 
diff --git a/src/main/java/org/jsoup/nodes/FormElement.java b/src/main/java/org/jsoup/nodes/FormElement.java
index 25e5fa5431..4d5007eb07 100644
--- a/src/main/java/org/jsoup/nodes/FormElement.java
+++ b/src/main/java/org/jsoup/nodes/FormElement.java
@@ -10,18 +10,19 @@
 import org.jsoup.select.Elements;
 import org.jsoup.select.Evaluator;
 import org.jsoup.select.QueryParser;
+import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * A HTML Form Element provides ready access to the form fields/controls that are associated with it. It also allows a
+ * An HTML Form Element provides ready access to the form fields/controls that are associated with it. It also allows a
  * form to easily be submitted.
  */
 public class FormElement extends Element {
-    private Elements linkedEls = new Elements();
+    private final Elements linkedEls = new Elements();
     // contains form submittable elements that were linked during the parse (and due to parse rules, may no longer be a child of this form)
-    private final Evaluator submitable = QueryParser.parse(StringUtil.join(SharedConstants.FormSubmitTags, ", "));
+    private final Evaluator submittable = QueryParser.parse(StringUtil.join(SharedConstants.FormSubmitTags, ", "));
 
     /**
      * Create a new, standalone form element.
@@ -30,7 +31,7 @@ public class FormElement extends Element {
      * @param baseUri    the base URI
      * @param attributes initial attributes
      */
-    public FormElement(Tag tag, String baseUri, Attributes attributes) {
+    public FormElement(Tag tag, @Nullable String baseUri, @Nullable Attributes attributes) {
         super(tag, baseUri, attributes);
     }
 
@@ -40,7 +41,7 @@ public FormElement(Tag tag, String baseUri, Attributes attributes) {
      */
     public Elements elements() {
         // As elements may have been added or removed from the DOM after parse, prepare a new list that unions them:
-        Elements els = select(submitable); // current form children
+        Elements els = select(submittable); // current form children
         for (Element linkedEl : linkedEls) {
             if (linkedEl.ownerDocument() != null && !els.contains(linkedEl)) {
                 els.add(linkedEl); // adds previously linked elements, that weren't previously removed from the DOM
diff --git a/src/main/java/org/jsoup/nodes/LeafNode.java b/src/main/java/org/jsoup/nodes/LeafNode.java
index 8e5df5f07a..ade5fece11 100644
--- a/src/main/java/org/jsoup/nodes/LeafNode.java
+++ b/src/main/java/org/jsoup/nodes/LeafNode.java
@@ -75,7 +75,7 @@ public String absUrl(String key) {
 
     @Override
     public String baseUri() {
-        return hasParent() ? parent().baseUri() : "";
+        return parentNode != null ? parentNode.baseUri() : "";
     }
 
     @Override
diff --git a/src/main/java/org/jsoup/nodes/Node.java b/src/main/java/org/jsoup/nodes/Node.java
index 856851eca2..2e9d66f089 100644
--- a/src/main/java/org/jsoup/nodes/Node.java
+++ b/src/main/java/org/jsoup/nodes/Node.java
@@ -418,7 +418,7 @@ private void addSiblingHtml(int index, String html) {
         Validate.notNull(html);
         Validate.notNull(parentNode);
 
-        Element context = parent() instanceof Element ? (Element) parent() : null;
+        Element context = parentNode instanceof Element ? (Element) parentNode : null;
         List<Node> nodes = NodeUtils.parser(this).parseFragmentInput(html, context, baseUri());
         parentNode.addChildren(index, nodes.toArray(new Node[0]));
     }
@@ -490,7 +490,7 @@ public Node wrap(String html) {
         return firstChild;
     }
 
-    private Element getDeepChild(Element el) {
+    private static Element getDeepChild(Element el) {
         Element child = el.firstElementChild();
         while (child != null) {
             el = child;
@@ -944,7 +944,7 @@ private static class OuterHtmlVisitor implements NodeVisitor {
             this.out = out;
         }
 
-        public void head(Node node, int depth) {
+        @Override public void head(Node node, int depth) {
             try {
 				node.outerHtmlHead(accum, depth, out);
 			} catch (IOException exception) {
@@ -952,7 +952,7 @@ public void head(Node node, int depth) {
 			}
         }
 
-        public void tail(Node node, int depth) {
+        @Override public void tail(Node node, int depth) {
             if (!node.nodeName().equals("#text")) { // saves a void hit.
 				try {
 					node.outerHtmlTail(accum, depth, out);
diff --git a/src/main/java/org/jsoup/nodes/NodeUtils.java b/src/main/java/org/jsoup/nodes/NodeUtils.java
index 6d3bb814ab..f56219cc63 100644
--- a/src/main/java/org/jsoup/nodes/NodeUtils.java
+++ b/src/main/java/org/jsoup/nodes/NodeUtils.java
@@ -32,7 +32,7 @@ static Document.OutputSettings outputSettings(Node node) {
      */
     static Parser parser(Node node) {
         Document doc = node.ownerDocument();
-        return doc != null && doc.parser() != null ? doc.parser() : new Parser(new HtmlTreeBuilder());
+        return doc != null ? doc.parser() : new Parser(new HtmlTreeBuilder());
     }
 
     /**
diff --git a/src/main/java/org/jsoup/nodes/Range.java b/src/main/java/org/jsoup/nodes/Range.java
index 1a665f8857..7cdac1b660 100644
--- a/src/main/java/org/jsoup/nodes/Range.java
+++ b/src/main/java/org/jsoup/nodes/Range.java
@@ -1,5 +1,7 @@
 package org.jsoup.nodes;
 
+import org.jsoup.internal.StringUtil;
+
 import java.util.Objects;
 
 import static org.jsoup.internal.SharedConstants.*;
@@ -228,7 +230,11 @@ public Range valueRange() {
          {@code line,column:pos-line,column:pos=line,column:pos-line,column:pos} (name start - name end = val start - val end).
          . */
         @Override public String toString() {
-            return nameRange().toString() + "=" + valueRange().toString();
+            StringBuilder sb = StringUtil.borrowBuilder()
+                .append(nameRange)
+                .append('=')
+                .append(valueRange);
+            return StringUtil.releaseBuilder(sb);
         }
 
         @Override public boolean equals(Object o) {
diff --git a/src/main/java/org/jsoup/nodes/TextNode.java b/src/main/java/org/jsoup/nodes/TextNode.java
index fe795c9f40..5bbb19ee55 100644
--- a/src/main/java/org/jsoup/nodes/TextNode.java
+++ b/src/main/java/org/jsoup/nodes/TextNode.java
@@ -20,7 +20,7 @@ public TextNode(String text) {
         value = text;
     }
 
-	public String nodeName() {
+	@Override public String nodeName() {
         return "#text";
     }
     
diff --git a/src/main/java/org/jsoup/nodes/XmlDeclaration.java b/src/main/java/org/jsoup/nodes/XmlDeclaration.java
index 8cd2932ced..a032d0fd9a 100644
--- a/src/main/java/org/jsoup/nodes/XmlDeclaration.java
+++ b/src/main/java/org/jsoup/nodes/XmlDeclaration.java
@@ -24,7 +24,7 @@ public XmlDeclaration(String name, boolean isProcessingInstruction) {
         this.isProcessingInstruction = isProcessingInstruction;
     }
 
-    public String nodeName() {
+    @Override public String nodeName() {
         return "#declaration";
     }
 
diff --git a/src/main/java/org/jsoup/parser/Parser.java b/src/main/java/org/jsoup/parser/Parser.java
index 7c03560f10..538413d43b 100644
--- a/src/main/java/org/jsoup/parser/Parser.java
+++ b/src/main/java/org/jsoup/parser/Parser.java
@@ -3,6 +3,7 @@
 import org.jsoup.nodes.Document;
 import org.jsoup.nodes.Element;
 import org.jsoup.nodes.Node;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Reader;
 import java.io.StringReader;
@@ -57,7 +58,7 @@ public Document parseInput(Reader inputHtml, String baseUri) {
         return treeBuilder.parse(inputHtml, baseUri, this);
     }
 
-    public List<Node> parseFragmentInput(String fragment, Element context, String baseUri) {
+    public List<Node> parseFragmentInput(String fragment, @Nullable Element context, String baseUri) {
         return treeBuilder.parseFragment(fragment, context, baseUri, this);
     }
     // gets & sets