From 6978f0a398203b85132162abd12bacecd6205791 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Sun, 24 Aug 2025 14:02:04 +0200
Subject: [PATCH] Document terms and units in DataSize.parse(...) methods

Closes gh-35298
---
 .../springframework/util/unit/DataSize.java   | 40 ++++++++++++-------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/util/unit/DataSize.java b/spring-core/src/main/java/org/springframework/util/unit/DataSize.java
index 002c5241333..35b85821efe 100644
--- a/spring-core/src/main/java/org/springframework/util/unit/DataSize.java
+++ b/spring-core/src/main/java/org/springframework/util/unit/DataSize.java
@@ -137,14 +137,19 @@ public final class DataSize implements Comparable<DataSize>, Serializable {
 	}
 
 	/**
-	 * Obtain a {@link DataSize} from a text string such as {@code 12MB} using
+	 * Obtain a {@link DataSize} from a text string such as {@code "5MB"} using
 	 * {@link DataUnit#BYTES} if no unit is specified.
-	 * <p>Examples:
-	 * <pre>
-	 * "12KB" -- parses as "12 kilobytes"
-	 * "5MB"  -- parses as "5 megabytes"
-	 * "20"   -- parses as "20 bytes"
-	 * </pre>
+	 * <h4>Examples</h4>
+	 * <table border="1">
+	 * <tr><th>Text</th><th>Parsed As</th><th>Size in Bytes</th></tr>
+	 * <tr><td>"20"</td><td>20 bytes</td><td>20</td></tr>
+	 * <tr><td>"20B"</td><td>20 bytes</td><td>20</td></tr>
+	 * <tr><td>"12KB"</td><td>12 kilobytes</td><td>12,288</td></tr>
+	 * <tr><td>"5MB"</td><td>5 megabytes</td><td>5,242,880</td></tr>
+	 * </table>
+	 * <p>Note that the terms and units used in the above examples are based on
+	 * <a href="https://en.wikipedia.org/wiki/Binary_prefix">binary prefixes</a>.
+	 * Consult the {@linkplain DataSize class-level Javadoc} for details.
 	 * @param text the text to parse
 	 * @return the parsed {@code DataSize}
 	 * @see #parse(CharSequence, DataUnit)
@@ -154,19 +159,24 @@ public final class DataSize implements Comparable<DataSize>, Serializable {
 	}
 
 	/**
-	 * Obtain a {@link DataSize} from a text string such as {@code 12MB} using
+	 * Obtain a {@link DataSize} from a text string such as {@code "5MB"} using
 	 * the specified default {@link DataUnit} if no unit is specified.
 	 * <p>The string starts with a number followed optionally by a unit matching
 	 * one of the supported {@linkplain DataUnit suffixes}.
 	 * <p>If neither a unit nor a default {@code DataUnit} is specified,
 	 * {@link DataUnit#BYTES} will be inferred.
-	 * <p>Examples:
-	 * <pre>
-	 * "12KB" -- parses as "12 kilobytes"
-	 * "5MB"  -- parses as "5 megabytes"
-	 * "20"   -- parses as "20 kilobytes" (where the {@code defaultUnit} is {@link DataUnit#KILOBYTES})
-	 * "20"   -- parses as "20 bytes" (if the {@code defaultUnit} is {@code null})
-	 * </pre>
+	 * <h4>Examples</h4>
+	 * <table border="1">
+	 * <tr><th>Text</th><th>Default Unit</th><th>Parsed As</th><th>Size in Bytes</th></tr>
+	 * <tr><td>"20"</td><td>{@code null}</td><td>20 bytes</td><td>20</td></tr>
+	 * <tr><td>"20"</td><td>{@link DataUnit#KILOBYTES KILOBYTES}</td><td>20 kilobytes</td><td>20,480</td></tr>
+	 * <tr><td>"20B"</td><td>N/A</td><td>20 bytes</td><td>20</td></tr>
+	 * <tr><td>"12KB"</td><td>N/A</td><td>12 kilobytes</td><td>12,288</td></tr>
+	 * <tr><td>"5MB"</td><td>N/A</td><td>5 megabytes</td><td>5,242,880</td></tr>
+	 * </table>
+	 * <p>Note that the terms and units used in the above examples are based on
+	 * <a href="https://en.wikipedia.org/wiki/Binary_prefix">binary prefixes</a>.
+	 * Consult the {@linkplain DataSize class-level Javadoc} for details.
 	 * @param text the text to parse
 	 * @param defaultUnit the default {@code DataUnit} to use
 	 * @return the parsed {@code DataSize}