LUCENE-2946: put vint table from fileformats in writeVInt

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1330511 13f79535-47bb-0310-9956-ffa450edef68

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

@@ -79,6 +79,9 @@ public abstract class DataInput implements Cloneable {
   /** Reads an int stored in variable-length format.  Reads between one and
    * five bytes.  Smaller values take fewer bytes.  Negative numbers are not
    * supported.
+   * <p>
+   * The format is described further in {@link DataOutput#writeVInt(int)}.
+   * 
    * @see DataOutput#writeVInt(int)
    */
   public int readVInt() throws IOException {
@@ -121,7 +124,12 @@ public abstract class DataInput implements Cloneable {
 
   /** Reads a long stored in variable-length format.  Reads between one and
    * nine bytes.  Smaller values take fewer bytes.  Negative numbers are not
-   * supported. */
+   * supported.
+   * <p>
+   * The format is described further in {@link DataOutput#writeVInt(int)}.
+   * 
+   * @see DataOutput#writeVLong(long)
+   */
   public long readVLong() throws IOException {
     /* This is the original code of this method,
      * but a Hotspot bug (see LUCENE-2975) corrupts the for-loop if

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

@@ -72,6 +72,107 @@ public abstract class DataOutput {
   /** Writes an int in a variable-length format.  Writes between one and
    * five bytes.  Smaller values take fewer bytes.  Negative numbers are
    * supported, but should be avoided.
+   * <p>VByte is a variable-length format for positive integers is defined where the
+   * high-order bit of each byte indicates whether more bytes remain to be read. The
+   * low-order seven bits are appended as increasingly more significant bits in the
+   * resulting integer value. Thus values from zero to 127 may be stored in a single
+   * byte, values from 128 to 16,383 may be stored in two bytes, and so on.</p>
+   * <p>VByte Encoding Example</p>
+   * <table cellspacing="0" cellpadding="2" border="0">
+   * <col width="64*">
+   * <col width="64*">
+   * <col width="64*">
+   * <col width="64*">
+   * <tr valign="top">
+   *   <th align="left" width="25%">Value</th>
+   *   <th align="left" width="25%">Byte 1</th>
+   *   <th align="left" width="25%">Byte 2</th>
+   *   <th align="left" width="25%">Byte 3</th>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">0</td>
+   *   <td width="25%"><kbd>00000000</kbd></td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">1</td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">2</td>
+   *   <td width="25%"><kbd>00000010</kbd></td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr>
+   *   <td valign="top" width="25%">...</td>
+   *   <td valign="bottom" width="25%"></td>
+   *   <td valign="bottom" width="25%"></td>
+   *   <td valign="bottom" width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">127</td>
+   *   <td width="25%"><kbd>01111111</kbd></td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">128</td>
+   *   <td width="25%"><kbd>10000000</kbd></td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">129</td>
+   *   <td width="25%"><kbd>10000001</kbd></td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">130</td>
+   *   <td width="25%"><kbd>10000010</kbd></td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr>
+   *   <td valign="top" width="25%">...</td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">16,383</td>
+   *   <td width="25%"><kbd>11111111</kbd></td>
+   *   <td width="25%"><kbd>01111111</kbd></td>
+   *   <td width="25%"></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">16,384</td>
+   *   <td width="25%"><kbd>10000000</kbd></td>
+   *   <td width="25%"><kbd>10000000</kbd></td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   * </tr>
+   * <tr valign="bottom">
+   *   <td width="25%">16,385</td>
+   *   <td width="25%"><kbd>10000001</kbd></td>
+   *   <td width="25%"><kbd>10000000</kbd></td>
+   *   <td width="25%"><kbd>00000001</kbd></td>
+   * </tr>
+   * <tr>
+   *   <td valign="top" width="25%">...</td>
+   *   <td valign="bottom" width="25%"></td>
+   *   <td valign="bottom" width="25%"></td>
+   *   <td valign="bottom" width="25%"></td>
+   * </tr>
+   * </table>
+   * <p>This provides compression while still being efficient to decode.</p>
+   * 
+   * @param i Smaller values take fewer bytes.  Negative numbers are
+   * supported, but should be avoided.
+   * @throws IOException If there is an I/O error writing to the underlying medium.
    * @see DataInput#readVInt()
    */
   public final void writeVInt(int i) throws IOException {
@@ -93,6 +194,8 @@ public abstract class DataOutput {
   /** Writes an long in a variable-length format.  Writes between one and nine
    * bytes.  Smaller values take fewer bytes.  Negative numbers are not
    * supported.
+   * <p>
+   * The format is described further in {@link DataOutput#writeVInt(int)}.
    * @see DataInput#readVLong()
    */
   public final void writeVLong(long i) throws IOException {