[LUCENE-10148] Fix DataInput/Output javadocs, MIGRATE.txt to document endianness

• Type: Task
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 9.0
• Fix Version/s: 9.0
• Lucene Fields: New
• Assignee: Unassigned
• Reporter: Robert Muir
• Created: 05/Oct/21 11:51
• Updated: 28/Aug/22 16:27
• Resolved: 05/Oct/21 17:04

Description

Currently docs look like this:

  /**
   * Reads two bytes and returns a short.
   */
public short readShort() throws IOException;

Let's improve them with more content, something like this at a minimum:

  /**
   * Reads two bytes and returns a short (LE byte order).
   *
   * @see BitUtil#VH_LE_SHORT
   */
public short readShort() throws IOException;

Also, because these methods were defined previously in Lucene 8.x versions to be big-endian, but are now little-endian, we should add a blurb to MIGRATE.md to call this change out better, to reduce surprises: