Fix DataInput/Output/RandomAccessInput javadocs, MIGRATE.txt to document endianness

Better document these methods directly, mentioning endianness, linking
to appropriate varhandle constant, etc.

Add blurb to MIGRATE.txt to call out the switch to little-endian to
increase awareness.

lucene/MIGRATE.md

@@ -17,6 +17,12 @@
 
 # Apache Lucene Migration Guide
 
+## Directory API is now little endian (LUCENE-9047)
+
+DataOutput's writeShort, writeInt, and writeLong methods now encode with
+LE byte order. If you have custom subclasses of DataInput/DataOutput, you
+will need to adjust them from BE byte order to LE byte order.
+
 ## NativeUnixDirectory removed and replaced by DirectIODirectory (LUCENE-8982)
 
 Java 11 supports to use Direct IO without native wrappers from Java code.

lucene/core/src/java/org/apache/lucene/store/DataInput.java

@@ -73,9 +73,10 @@ public abstract class DataInput implements Cloneable {
   }
 
   /**
-   * Reads two bytes and returns a short.
+   * Reads two bytes and returns a short (LE byte order).
    *
-   * @see DataOutput#writeByte(byte)
+   * @see DataOutput#writeShort(short)
+   * @see BitUtil#VH_LE_SHORT
    */
   public short readShort() throws IOException {
     final byte b1 = readByte();
@@ -84,9 +85,10 @@ public abstract class DataInput implements Cloneable {
   }
 
   /**
-   * Reads four bytes and returns an int.
+   * Reads four bytes and returns an int (LE byte order).
    *
    * @see DataOutput#writeInt(int)
+   * @see BitUtil#VH_LE_INT
    */
   public int readInt() throws IOException {
     final byte b1 = readByte();
@@ -146,9 +148,10 @@ public abstract class DataInput implements Cloneable {
   }
 
   /**
-   * Reads eight bytes and returns a long.
+   * Reads eight bytes and returns a long (LE byte order).
    *
    * @see DataOutput#writeLong(long)
+   * @see BitUtil#VH_LE_LONG
    */
   public long readLong() throws IOException {
     return (readInt() & 0xFFFFFFFFL) | (((long) readInt()) << 32);

lucene/core/src/java/org/apache/lucene/store/DataOutput.java

@@ -63,11 +63,10 @@ public abstract class DataOutput {
   public abstract void writeBytes(byte[] b, int offset, int length) throws IOException;
 
   /**
-   * Writes an int as four bytes.
-   *
-   * <p>32-bit unsigned integer written as four bytes, low-order bytes first.
+   * Writes an int as four bytes (LE byte order).
    *
    * @see DataInput#readInt()
+   * @see BitUtil#VH_LE_INT
    */
   public void writeInt(int i) throws IOException {
     writeByte((byte) i);
@@ -77,9 +76,10 @@ public abstract class DataOutput {
   }
 
   /**
-   * Writes a short as two bytes.
+   * Writes a short as two bytes (LE byte order).
    *
    * @see DataInput#readShort()
+   * @see BitUtil#VH_LE_SHORT
    */
   public void writeShort(short i) throws IOException {
     writeByte((byte) i);
@@ -215,11 +215,10 @@ public abstract class DataOutput {
   }
 
   /**
-   * Writes a long as eight bytes.
-   *
-   * <p>64-bit unsigned integer written as eight bytes, low-order bytes first.
+   * Writes a long as eight bytes (LE byte order).
    *
    * @see DataInput#readLong()
+   * @see BitUtil#VH_LE_LONG
    */
   public void writeLong(long i) throws IOException {
     writeInt((int) i);

lucene/core/src/java/org/apache/lucene/store/RandomAccessInput.java

@@ -17,6 +17,7 @@
 package org.apache.lucene.store;
 
 import java.io.IOException;
+import org.apache.lucene.util.BitUtil; // javadocs
 
 /**
  * Random Access Index API. Unlike {@link IndexInput}, this has no concept of file position, all
@@ -31,21 +32,24 @@ public interface RandomAccessInput {
    */
   public byte readByte(long pos) throws IOException;
   /**
-   * Reads a short at the given position in the file
+   * Reads a short (LE byte order) at the given position in the file
    *
    * @see DataInput#readShort
+   * @see BitUtil#VH_LE_SHORT
    */
   public short readShort(long pos) throws IOException;
   /**
-   * Reads an integer at the given position in the file
+   * Reads an integer (LE byte order) at the given position in the file
    *
    * @see DataInput#readInt
+   * @see BitUtil#VH_LE_INT
    */
   public int readInt(long pos) throws IOException;
   /**
-   * Reads a long at the given position in the file
+   * Reads a long (LE byte order) at the given position in the file
    *
    * @see DataInput#readLong
+   * @see BitUtil#VH_LE_LONG
    */
   public long readLong(long pos) throws IOException;
 }