From 059d610de8155144c9707dbd663f25586b9998dd Mon Sep 17 00:00:00 2001
From: Adrien Grand <jpountz@apache.org>
Date: Sat, 26 Jan 2013 13:24:44 +0000
Subject: [PATCH] More format docs.

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/lucene4547@1438892 13f79535-47bb-0310-9956-ffa450edef68
---
 .../lucene/util/packed/BlockPackedWriter.java | 23 +++++++++++++++
 .../packed/MonotonicBlockPackedWriter.java    | 28 ++++++++++++++++---
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/lucene/core/src/java/org/apache/lucene/util/packed/BlockPackedWriter.java b/lucene/core/src/java/org/apache/lucene/util/packed/BlockPackedWriter.java
index 4deb6ec20aa..6c39b87f98c 100644
--- a/lucene/core/src/java/org/apache/lucene/util/packed/BlockPackedWriter.java
+++ b/lucene/core/src/java/org/apache/lucene/util/packed/BlockPackedWriter.java
@@ -29,7 +29,30 @@ import org.apache.lucene.store.DataOutput;
  * using as few bits as possible. Memory usage of this class is proportional to
  * the block size. Each block has an overhead between 1 and 10 bytes to store
  * the minimum value and the number of bits per value of the block.
+ * <p>
+ * Format:
+ * <ul>
+ * <li>&lt;BLock&gt;<sup>BlockCount</sup>
+ * <li>BlockCount: &lceil; ValueCount / BlockSize &rceil;
+ * <li>Block: &lt;Header, (Ints)&gt;
+ * <li>Header: &lt;Token, (MinValue)&gt;
+ * <li>Token: a {@link DataOutput#writeByte(byte) byte}, first 7 bits are the
+ *     number of bits per value (<tt>bitsPerValue</tt>). If the 8th bit is 1,
+ *     then MinValue (see next) is <tt>0</tt>, otherwise MinValue and needs to
+ *     be decoded
+ * <li>MinValue: a
+ *     <a href="https://developers.google.com/protocol-buffers/docs/encoding#types">zigzag-encoded</a>
+ *     {@link DataOutput#writeVLong(long) variable-length long} whose value
+ *     should be added to every int from the block to restore the original
+ *     values
+ * <li>Ints: If the number of bits per value is <tt>0</tt>, then there is
+ *     nothing to decode and all ints are equal to MinValue. Otherwise: BlockSize
+ *     {@link PackedInts packed ints} encoded on exactly <tt>bitsPerValue</tt>
+ *     bits per value. They are the subtraction of the original values and
+ *     MinValue
+ * </ul>
  * @see BlockPackedReaderIterator
+ * @see BlockPackedReader
  * @lucene.internal
  */
 public final class BlockPackedWriter extends AbstractBlockPackedWriter {
diff --git a/lucene/core/src/java/org/apache/lucene/util/packed/MonotonicBlockPackedWriter.java b/lucene/core/src/java/org/apache/lucene/util/packed/MonotonicBlockPackedWriter.java
index 500f9392c71..a56d76fc19d 100644
--- a/lucene/core/src/java/org/apache/lucene/util/packed/MonotonicBlockPackedWriter.java
+++ b/lucene/core/src/java/org/apache/lucene/util/packed/MonotonicBlockPackedWriter.java
@@ -24,10 +24,30 @@ import org.apache.lucene.store.DataOutput;
 /**
  * A writer for large monotonically increasing sequences of positive longs.
  * <p>
- * The sequence is divided into fixed-size blocks and for each block, the
- * average value per ord is computed, followed by the delta from the expected
- * value for every ord, using as few bits as possible. Each block has an
- * overhead between 6 and 14 bytes.
+ * The sequence is divided into fixed-size blocks and for each block, values
+ * are modeled after a linear function f: x &rarr; A &times; x + B. The block
+ * encodes deltas from the expected values computed from this function using as
+ * few bits as possible. Each block has an overhead between 6 and 14 bytes.
+ * <p>
+ * Format:
+ * <ul>
+ * <li>&lt;BLock&gt;<sup>BlockCount</sup>
+ * <li>BlockCount: &lceil; ValueCount / BlockSize &rceil;
+ * <li>Block: &lt;Header, (Ints)&gt;
+ * <li>Header: &lt;B, A, BitsPerValue&gt;
+ * <li>B: the B from f: x &rarr; A &times; x + B using a
+ *     {@link DataOutput#writeVLong(long) variable-length long}
+ * <li>A: the A from f: x &rarr; A &times; x + B encoded using
+ *     {@link Float#floatToIntBits(float)} on
+ *     {@link DataOutput#writeInt(int) 4 bytes}
+ * <li>BitsPerValue: a {@link DataOutput#writeVInt(int) variable-length int}
+ * <li>Ints: if BitsPerValue is <tt>0</tt>, then there is nothing to read and
+ *     all values perfectly match the result of the function. Otherwise, these
+ *     are the
+ *     <a href="https://developers.google.com/protocol-buffers/docs/encoding#types">zigzag-encoded</a>
+ *     {@link PackedInts packed} deltas from the expected value (computed from
+ *     the function) using exaclty BitsPerValue bits per value
+ * </ul>
  * @see MonotonicBlockPackedReader
  * @lucene.internal
  */