From 4fc0725cf9fdc1f32793d0a2a52a4a12492242f1 Mon Sep 17 00:00:00 2001
From: daguimu <daguimu.geek@gmail.com>
Date: Thu, 26 Mar 2026 10:02:28 +0800
Subject: [PATCH] Add explicit writeUTF/readUTF javadoc to LittleEndian stream
 classes.

The inherited javadoc from DataOutput/DataInput references writeShort
and readUnsignedShort for the UTF length prefix, which in these classes
use little-endian byte order. However, writeUTF/readUTF actually
delegate to standard DataOutputStream/DataInputStream, which use
big-endian for the length prefix. This is misleading.

Added explicit javadoc to clarify that the 2-byte UTF length prefix
uses big-endian byte order, unlike the other methods in these classes.

Fixes #1659
---
 .../google/common/io/LittleEndianDataInputStream.java  | 10 ++++++++++
 .../google/common/io/LittleEndianDataOutputStream.java |  9 +++++++++
 .../google/common/io/LittleEndianDataInputStream.java  | 10 ++++++++++
 .../google/common/io/LittleEndianDataOutputStream.java |  9 +++++++++
 4 files changed, 38 insertions(+)

diff --git a/android/guava/src/com/google/common/io/LittleEndianDataInputStream.java b/android/guava/src/com/google/common/io/LittleEndianDataInputStream.java
index 9e2f05e7413c..4f87c613318e 100644
--- a/android/guava/src/com/google/common/io/LittleEndianDataInputStream.java
+++ b/android/guava/src/com/google/common/io/LittleEndianDataInputStream.java
@@ -173,6 +173,16 @@ public double readDouble() throws IOException {
     return Double.longBitsToDouble(readLong());
   }
 
+  /**
+   * Reads a string as specified by {@link DataInputStream#readUTF()}.
+   *
+   * <p>The UTF-8 encoded string is prefixed by a 2-byte length in <b>big-endian</b> byte order,
+   * not little-endian. This matches the behavior of {@link DataInputStream} and is not affected by
+   * the little-endian byte order used by other read methods in this class.
+   *
+   * @return the string read from the input stream
+   * @throws IOException if an I/O error occurs
+   */
   @CanIgnoreReturnValue // to skip a field
   @Override
   public String readUTF() throws IOException {
diff --git a/android/guava/src/com/google/common/io/LittleEndianDataOutputStream.java b/android/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
index dd3746cc6781..2de87250c35a 100644
--- a/android/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
+++ b/android/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
@@ -156,6 +156,15 @@ public void writeShort(int v) throws IOException {
     out.write(0xFF & (v >> 8));
   }
 
+  /**
+   * Writes a string as specified by {@link DataOutputStream#writeUTF(String)}.
+   *
+   * <p>The UTF-8 encoded string is prefixed by a 2-byte length in <b>big-endian</b> byte order,
+   * not little-endian. This matches the behavior of {@link DataOutputStream} and is not affected by
+   * the little-endian byte order used by other write methods in this class.
+   *
+   * @throws IOException if an I/O error occurs
+   */
   @Override
   public void writeUTF(String str) throws IOException {
     ((DataOutputStream) out).writeUTF(str);
diff --git a/guava/src/com/google/common/io/LittleEndianDataInputStream.java b/guava/src/com/google/common/io/LittleEndianDataInputStream.java
index 9e2f05e7413c..4f87c613318e 100644
--- a/guava/src/com/google/common/io/LittleEndianDataInputStream.java
+++ b/guava/src/com/google/common/io/LittleEndianDataInputStream.java
@@ -173,6 +173,16 @@ public double readDouble() throws IOException {
     return Double.longBitsToDouble(readLong());
   }
 
+  /**
+   * Reads a string as specified by {@link DataInputStream#readUTF()}.
+   *
+   * <p>The UTF-8 encoded string is prefixed by a 2-byte length in <b>big-endian</b> byte order,
+   * not little-endian. This matches the behavior of {@link DataInputStream} and is not affected by
+   * the little-endian byte order used by other read methods in this class.
+   *
+   * @return the string read from the input stream
+   * @throws IOException if an I/O error occurs
+   */
   @CanIgnoreReturnValue // to skip a field
   @Override
   public String readUTF() throws IOException {
diff --git a/guava/src/com/google/common/io/LittleEndianDataOutputStream.java b/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
index dd3746cc6781..2de87250c35a 100644
--- a/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
+++ b/guava/src/com/google/common/io/LittleEndianDataOutputStream.java
@@ -156,6 +156,15 @@ public void writeShort(int v) throws IOException {
     out.write(0xFF & (v >> 8));
   }
 
+  /**
+   * Writes a string as specified by {@link DataOutputStream#writeUTF(String)}.
+   *
+   * <p>The UTF-8 encoded string is prefixed by a 2-byte length in <b>big-endian</b> byte order,
+   * not little-endian. This matches the behavior of {@link DataOutputStream} and is not affected by
+   * the little-endian byte order used by other write methods in this class.
+   *
+   * @throws IOException if an I/O error occurs
+   */
   @Override
   public void writeUTF(String str) throws IOException {
     ((DataOutputStream) out).writeUTF(str);