Mark deprecated methods as slated for removal in 1.24.1

Author: jhy

CHANGES.md

@@ -18,6 +18,9 @@
 * Build: added CI coverage for JDK 25 [#2403](https://github.com/jhy/jsoup/pull/2403)
 * Build: added a CI fuzzer for contextual fragment parsing (in addition to existing full body HTML and XML fuzzers). [oss-fuzz #14041](https://github.com/google/oss-fuzz/pull/14041)
 
+### Changes
+* Set a removal schedule of jsoup 1.24.1 for previously deprecated APIs.
+
 ### Bug Fixes
 * Previously cached child Elements of an Element were not correctly invalidated in `Node#replaceWith(Node)`, which could lead to incorrect results when subsequently calling `Element#children()`. [#2391](https://github.com/jhy/jsoup/issues/2391)
 * Attribute selector values are now compared literally without trimming. Previously, jsoup trimmed whitespace from selector values and from element attribute values, which could cause mismatches with browser behavior (e.g. `[attr=" foo "]`). Now matches align with the CSS specification and browser engines. [#2380](https://github.com/jhy/jsoup/issues/2380)

src/main/java/org/jsoup/Connection.java

@@ -218,7 +218,7 @@ default Connection newRequest(URL url) {
      @param sslSocketFactory SSL socket factory
      @return this Connection, for chaining
      @see #sslContext(SSLContext)
-     @deprecated use {@link #sslContext(SSLContext)} instead.
+     @deprecated use {@link #sslContext(SSLContext)} instead; will be removed in jsoup 1.24.1.
      */
     @Deprecated
     Connection sslSocketFactory(SSLSocketFactory sslSocketFactory);
@@ -795,7 +795,7 @@ interface Request extends Base<Request> {
 
          @param sslSocketFactory SSL socket factory
          @see #sslContext(SSLContext)
-         @deprecated use {@link #sslContext(SSLContext)} instead.
+         @deprecated use {@link #sslContext(SSLContext)} instead; will be removed in jsoup 1.24.1.
          */
         @Deprecated
         void sslSocketFactory(SSLSocketFactory sslSocketFactory);
@@ -1033,7 +1033,7 @@ default Response readFully() throws IOException {
          * <p>Calling {@link #body() } or {@link #bodyAsBytes()} has the same effect.</p>
          * @return this response, for chaining
          * @throws UncheckedIOException if an IO exception occurs during buffering.
-         * @deprecated use {@link #readFully()} instead (for the checked exception). Will be removed in a future version.
+         * @deprecated use {@link #readFully()} instead (for the checked exception). Will be removed in jsoup 1.24.1.
          */
         @Deprecated
         Response bufferUp();

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

@@ -48,7 +48,7 @@ public static void notNull(@Nullable Object obj, String msg) {
      * @param obj nullable object to cast to not-null
      * @return the object, or throws an exception if it is null
      * @throws ValidationException if the object is null
-     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead
+     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead; will be removed in jsoup 1.24.1
      */
     @Deprecated
     public static Object ensureNotNull(@Nullable Object obj) {
@@ -65,7 +65,7 @@ public static Object ensureNotNull(@Nullable Object obj) {
      * @param args the arguments to the msg
      * @return the object, or throws an exception if it is null
      * @throws ValidationException if the object is null
-     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead
+     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead; will be removed in jsoup 1.24.1
      */
     @Deprecated
     public static Object ensureNotNull(@Nullable Object obj, String msg, Object... args) {

src/main/java/org/jsoup/internal/Normalizer.java

@@ -23,7 +23,8 @@ public static String normalize(final String input) {
 
     /**
      If a string literal, just lower case the string; otherwise lower-case and trim.
-     @deprecated internal function; will be removed in a future version.
+     @deprecated internal helper; replace with {@link #lowerCase(String)} for no-trim, or {@link #normalize(String)} for trim + lowercase.
+     Will be removed in jsoup 1.24.1.
      */
     @Deprecated
     public static String normalize(final String input, boolean isStringLiteral) {

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

@@ -202,13 +202,13 @@ static void html(String key, @Nullable String val, QuietAppendable accum, Docume
         htmlNoValidate(key, val, accum, out);
     }
 
-    /** @deprecated internal method and will be removed in a future version */
+    /** @deprecated internal method; use {@link #html(String, String, QuietAppendable, Document.OutputSettings)} with {@link org.jsoup.internal.QuietAppendable#wrap(Appendable)} instead. Will be removed in jsoup 1.24.1. */
     @Deprecated
     protected void html(Appendable accum, Document.OutputSettings out) throws IOException {
         html(key, val, accum, out);
     }
 
-    /** @deprecated internal method and will be removed in a future version */
+    /** @deprecated internal method; use {@link #html(String, String, QuietAppendable, Document.OutputSettings)} with {@link org.jsoup.internal.QuietAppendable#wrap(Appendable)} instead. Will be removed in jsoup 1.24.1. */
     @Deprecated
     protected static void html(String key, @Nullable String val, Appendable accum, Document.OutputSettings out) throws IOException {
         html(key, val, QuietAppendable.wrap(accum), out);
@@ -306,7 +306,7 @@ protected static boolean isDataAttribute(String key) {
      * 
      * @param out output settings
      * @return  Returns whether collapsible or not
-     * @deprecated internal method and will be removed in a future version
+     * @deprecated internal method; use {@link #shouldCollapseAttribute(String, String, Document.OutputSettings)} instead. Will be removed in jsoup 1.24.1.
      */
     @Deprecated
     protected final boolean shouldCollapseAttribute(Document.OutputSettings out) {

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

@@ -902,7 +902,7 @@ public String toString() {
         return outerHtml();
     }
 
-    /** @deprecated internal method moved into Printer; will be removed in a future version */
+    /** @deprecated internal method moved into Printer; will be removed in jsoup 1.24.1. */
     @Deprecated
     protected void indent(Appendable accum, int depth, Document.OutputSettings out) throws IOException {
         accum.append('\n').append(StringUtil.padding(depth * out.indentAmount(), out.maxPaddingWidth()));

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

@@ -6,7 +6,8 @@
 /**
  * Represents a {@link TextNode} as an {@link Element}, to enable text nodes to be selected with
  * the {@link org.jsoup.select.Selector} {@code :matchText} syntax.
- * @deprecated use {@link Element#selectNodes(String, Class)} instead, with selector of <code>::textnode</code> and class <code>TextNode</code>.
+ * @deprecated use {@link Element#selectNodes(String, Class)} instead, with selector of <code>::textnode</code> and class <code>TextNode</code>;
+ * will be removed in jsoup 1.24.1.
  */
 @Deprecated
 public class PseudoTextElement extends Element {

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

@@ -60,7 +60,7 @@ public class HtmlTreeBuilder extends TreeBuilder {
         "button", "fieldset", "input", "keygen", "object", "output", "select", "textarea"
     };
 
-    /** @deprecated This is not used anymore. Will be removed in a future release. */
+    /** @deprecated Not used anymore; configure parser depth via {@link Parser#setMaxDepth(int)}. Will be removed in jsoup 1.24.1. */
     @Deprecated
     public static final int MaxScopeSearchDepth = 100;
 

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

@@ -245,7 +245,7 @@ public boolean isBlock() {
      Get if this is an InlineContainer tag.
 
      @return true if an InlineContainer (which formats children as inline).
-     @deprecated setting is only used within the Printer. Will be removed in a future release.
+     @deprecated internal pretty-printing flag; use {@link #isInline()} or {@link #isBlock()} to check layout intent. Will be removed in jsoup 1.24.1.
      */
     @Deprecated public boolean formatAsBlock() {
         return (options & InlineContainer) != 0;

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

@@ -436,7 +436,7 @@ public AttributeKeyPair(String key, String value) {
 
         /**
          @deprecated since 1.22.1, use {@link #AttributeKeyPair(String, String)}; the previous trimQuoted parameter is no longer used.
-         This constructor will be removed in a future release.
+         This constructor will be removed in jsoup 1.24.1.
          */
         @Deprecated
         public AttributeKeyPair(String key, String value, boolean ignored) {
@@ -1046,7 +1046,7 @@ public String toString() {
     }
 
     /**
-     @deprecated This selector is deprecated and will be removed in a future version. Migrate to <code>::textnode</code> using the <code>Element#selectNodes()</code> method instead.
+     @deprecated This selector is deprecated and will be removed in jsoup 1.24.1. Migrate to <code>::textnode</code> using the <code>Element#selectNodes()</code> method instead.
      */
     @Deprecated
     public static final class MatchText extends Evaluator {
@@ -1056,7 +1056,7 @@ public MatchText() {
             // log a deprecated error on first use; users typically won't directly construct this Evaluator and so won't otherwise get deprecation warnings
             if (!loggedError) {
                 loggedError = true;
-                System.err.println("WARNING: :matchText selector is deprecated and will be removed in a future version. Use Element#selectNodes(String, Class) with selector ::textnode and class TextNode instead.");
+                System.err.println("WARNING: :matchText selector is deprecated and will be removed in jsoup 1.24.1. Use Element#selectNodes(String, Class) with selector ::textnode and class TextNode instead.");
             }
         }