Improved javadoc for StreamParser

Author: jhy

src/main/java/org/jsoup/helper/DataUtil.java

@@ -128,7 +128,7 @@ public static Document load(Path path, @Nullable String charsetName, String base
      * @param charset (optional) character set of input; specify {@code null} to attempt to autodetect from metadata.
      * A BOM in the file will always override this setting.
      * @param baseUri base URI of document, to resolve relative links against
-     * @param parser alternate {@link Parser#xmlParser() parser} to use.
+     * @param parser underlying HTML or XML parser to use.
 
      * @return Document
      * @throws IOException on IO error

src/main/java/org/jsoup/nodes/Element.java

@@ -472,7 +472,7 @@ public List<DataNode> dataNodes() {
      * @param cssQuery a {@link Selector} CSS-like query
      * @return an {@link Elements} list containing elements that match the query (empty if none match)
      * @see Selector selector query syntax
-     * @see QueryParser#parse(String)
+     * @see #select(Evaluator)
      * @throws Selector.SelectorParseException (unchecked) on an invalid CSS query.
      */
     public Elements select(String cssQuery) {
@@ -485,6 +485,7 @@ public Elements select(String cssQuery) {
      * repeatedly parsing the CSS query.
      * @param evaluator an element evaluator
      * @return an {@link Elements} list containing elements that match the query (empty if none match)
+     * @see QueryParser#parse(String)
      */
     public Elements select(Evaluator evaluator) {
         return Selector.select(evaluator, this);

src/main/java/org/jsoup/parser/StreamParser.java

@@ -29,9 +29,9 @@
  A StreamParser provides a progressive parse of its input. As each Element is completed, it is emitted via a Stream or
  Iterator interface. Elements returned will be complete with all their children, and an (empty) next sibling, if
  applicable.
- <p>Elements (or their children) may be removed from the DOM during the parse, for e.g. to conserve memory, providing a
- mechanism to parse an input document that would otherwise be too large to fit into memory, yet still providing a DOM
- interface to the document and its elements.</p>
+ <p>To conserve memory, you can {@link Node#remove() remove()} Elements (or their children) from the DOM during the
+ parse. This provides a mechanism to parse an input document that would otherwise be too large to fit into memory, yet
+ still providing a DOM interface to the document and its elements.</p>
  <p>
  Additionally, the parser provides a {@link #selectFirst(String query)} / {@link #selectNext(String query)}, which will
  run the parser until a hit is found, at which point the parse is suspended. It can be resumed via another
@@ -45,6 +45,8 @@ interface to the document and its elements.</p>
  New parsers should be used in each thread.</p>
  <p>If created via {@link Connection.Response#streamParser()}, or another Reader that is I/O backed, the iterator and
  stream consumers will throw an {@link java.io.UncheckedIOException} if the underlying Reader errors during read.</p>
+ <p>For examples, see the jsoup
+ <a href="https://jsoup.org/cookbook/input/streamparser-dom-sax">StreamParser cookbook.</a></p>
  @since 1.18.1
  */
 public class StreamParser implements Closeable {
@@ -204,6 +206,7 @@ public List<Node> completeFragment() throws IOException {
      @param query the {@link org.jsoup.select.Selector} query.
      @return the first matching {@link Element}, or {@code null} if there's no match
      @throws IOException if an I/O error occurs
+     @see #selectFirst(Evaluator)
      */
     public @Nullable Element selectFirst(String query) throws IOException {
         return selectFirst(QueryParser.parse(query));
@@ -228,9 +231,12 @@ public Element expectFirst(String query) throws IOException {
     /**
      Finds the first Element that matches the provided query. If the parsed Document does not already have a match, the
      input will be parsed until the first match is found, or the input is completely read.
+     <p>By providing a compiled evaluator vs a CSS selector, this method may be more efficient when executing the same
+     query against multiple documents.</p>
      @param eval the {@link org.jsoup.select.Selector} evaluator.
      @return the first matching {@link Element}, or {@code null} if there's no match
      @throws IOException if an I/O error occurs
+     @see QueryParser#parse(String)
      */
     public @Nullable Element selectFirst(Evaluator eval) throws IOException {
         final Document doc = document();
@@ -248,6 +254,7 @@ public Element expectFirst(String query) throws IOException {
      @param query the {@link org.jsoup.select.Selector} query.
      @return the next matching {@link Element}, or {@code null} if there's no match
      @throws IOException if an I/O error occurs
+     @see #selectNext(Evaluator)
      */
     public @Nullable Element selectNext(String query) throws IOException {
         return selectNext(QueryParser.parse(query));
@@ -272,9 +279,12 @@ public Element expectNext(String query) throws IOException {
     /**
      Finds the next Element that matches the provided query. The input will be parsed until the next match is found, or
      the input is completely read.
+     <p>By providing a compiled evaluator vs a CSS selector, this method may be more efficient when executing the same
+     query against multiple documents.</p>
      @param eval the {@link org.jsoup.select.Selector} evaluator.
      @return the next matching {@link Element}, or {@code null} if there's no match
      @throws IOException if an I/O error occurs
+     @see QueryParser#parse(String)
      */
     public @Nullable Element selectNext(Evaluator eval) throws IOException {
         try {

src/main/java/org/jsoup/select/Evaluator.java

@@ -22,7 +22,9 @@
 
 
 /**
- * Evaluates that an element matches the selector.
+ An Evaluator tests if an element meets the selector's requirements. Obtain an evaluator for a given CSS selector
+ with {@link QueryParser#parse}. If you are executing the same selector on many elements (or documents), it
+ can be more efficient to compile and reuse an Evaluator than to reparse the selector on each invocation of select().
  */
 public abstract class Evaluator {
     protected Evaluator() {

src/main/java/org/jsoup/select/QueryParser.java

@@ -35,7 +35,8 @@ private QueryParser(String query) {
     }
 
     /**
-     * Parse a CSS query into an Evaluator.
+     * Parse a CSS query into an Evaluator. If you are evaluating the same query repeatedly, it may be more efficient to
+     * parse it once and reuse the Evaluator.
      * @param query CSS query
      * @return Evaluator
      * @see Selector selector query syntax