Document terms and units in DataSize and DataUnit

Prior to this commit, it was not readily apparent what terms and units
such as kilobyte/KB and megabyte/MB represented numerically in DataSize
and DataUnit.

This commit clarifies that such terms and units are based on binary
prefixes for data (i.e., powers of 2 instead of powers of 10).

Closes gh-23697

spring-core/src/main/java/org/springframework/util/unit/DataSize.java

@@ -26,10 +26,27 @@ import org.springframework.util.StringUtils;
 /**
  * A data size, such as '12MB'.
  *
- * <p>This class models a size in terms of bytes and is immutable and thread-safe.
+ * <p>This class models data size in terms of bytes and is immutable and thread-safe.
+ *
+ * <p>The terms and units used in this class are based on
+ * <a href="https://en.wikipedia.org/wiki/Binary_prefix">binary prefixes</a>
+ * indicating multiplication by powers of 2. Consult the following table and
+ * the Javadoc for {@link DataUnit} for details.
+ *
+ * <p>
+ * <table border="1">
+ * <tr><th>Term</th><th>Data Size</th><th>Size in Bytes</th></tr>
+ * <tr><td>byte</td><td>1B</td><td>1</td></tr>
+ * <tr><td>kilobyte</td><td>1KB</td><td>1,024</td></tr>
+ * <tr><td>megabyte</td><td>1MB</td><td>1,048,576</td></tr>
+ * <tr><td>gigabyte</td><td>1GB</td><td>1,073,741,824</td></tr>
+ * <tr><td>terabyte</td><td>1TB</td><td>1,099,511,627,776</td></tr>
+ * </table>
  *
  * @author Stephane Nicoll
+ * @author Sam Brannen
  * @since 5.1
+ * @see DataUnit
  */
 public final class DataSize implements Comparable<DataSize> {
 
@@ -146,7 +163,7 @@ public final class DataSize implements Comparable<DataSize> {
 	 * 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 {@link DataUnit suffixes}.
+	 * supported {@linkplain DataUnit suffixes}.
 	 * <p>
 	 * Examples:
 	 * <pre>

spring-core/src/main/java/org/springframework/util/unit/DataUnit.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,35 +19,52 @@ package org.springframework.util.unit;
 import java.util.Objects;
 
 /**
- * A standard set of data size units.
+ * A standard set of {@link DataSize} units.
+ *
+ * <p>The unit prefixes used in this class are
+ * <a href="https://en.wikipedia.org/wiki/Binary_prefix">binary prefixes</a>
+ * indicating multiplication by powers of 2. The following table displays the
+ * enum constants defined in this class and corresponding values.
+ *
+ * <p>
+ * <table border="1">
+ * <tr><th>Constant</th><th>Data Size</th><th>Power&nbsp;of&nbsp;2</th><th>Size in Bytes</th></tr>
+ * <tr><td>{@link #BYTES}</td><td>1B</td><td>2^0</td><td>1</td></tr>
+ * <tr><td>{@link #KILOBYTES}</td><td>1KB</td><td>2^10</td><td>1,024</td></tr>
+ * <tr><td>{@link #MEGABYTES}</td><td>1MB</td><td>2^20</td><td>1,048,576</td></tr>
+ * <tr><td>{@link #GIGABYTES}</td><td>1GB</td><td>2^30</td><td>1,073,741,824</td></tr>
+ * <tr><td>{@link #TERABYTES}</td><td>1TB</td><td>2^40</td><td>1,099,511,627,776</td></tr>
+ * </table>
  *
  * @author Stephane Nicoll
+ * @author Sam Brannen
  * @since 5.1
+ * @see DataSize
  */
 public enum DataUnit {
 
 	/**
-	 * Bytes.
+	 * Bytes, represented by suffix {@code B}.
 	 */
 	BYTES("B", DataSize.ofBytes(1)),
 
 	/**
-	 * Kilobytes.
+	 * Kilobytes, represented by suffix {@code KB}.
 	 */
 	KILOBYTES("KB", DataSize.ofKilobytes(1)),
 
 	/**
-	 * Megabytes.
+	 * Megabytes, represented by suffix {@code MB}.
 	 */
 	MEGABYTES("MB", DataSize.ofMegabytes(1)),
 
 	/**
-	 * Gigabytes.
+	 * Gigabytes, represented by suffix {@code GB}.
 	 */
 	GIGABYTES("GB", DataSize.ofGigabytes(1)),
 
 	/**
-	 * Terabytes.
+	 * Terabytes, represented by suffix {@code TB}.
 	 */
 	TERABYTES("TB", DataSize.ofTerabytes(1));
 
@@ -68,10 +85,10 @@ public enum DataUnit {
 
 	/**
 	 * Return the {@link DataUnit} matching the specified {@code suffix}.
-	 * @param suffix one of the standard suffix
+	 * @param suffix one of the standard suffixes
 	 * @return the {@link DataUnit} matching the specified {@code suffix}
-	 * @throws IllegalArgumentException if the suffix does not match any
+	 * @throws IllegalArgumentException if the suffix does not match the suffix
-	 * of this enum's constants
+	 * of any of this enum's constants
 	 */
 	public static DataUnit fromSuffix(String suffix) {
 		for (DataUnit candidate : values()) {
@@ -79,7 +96,7 @@ public enum DataUnit {
 				return candidate;
 			}
 		}
-		throw new IllegalArgumentException("Unknown unit '" + suffix + "'");
+		throw new IllegalArgumentException("Unknown data unit suffix '" + suffix + "'");
 	}
 
 }