Expand block documentation

presto-common/src/main/java/com/facebook/presto/common/block/Block.java

@@ -25,7 +25,7 @@
 /**
  * A block packs positionCount values into a chunk of memory. How the values are packed,
  * whether compression is used, endianness, and other implementation details are up to the subclasses.
- * However, for purposes of API, you can think of a Block as a sequence of values that
+ * However, for purposes of API, you can think of a Block as a sequence of zero-indexed values that
  * can be read by calling the getter methods in this interface. For instance,
  * you can read positionCount bytes by calling
  * block.getByte(0), block.getByte(1), ... block.getByte(positionCount - 1).
@@ -51,6 +51,8 @@ default int getSliceLength(int position)
 
     /**
      * Gets a byte in the value at {@code position}.
+     *
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default byte getByte(int position)
     {
@@ -59,6 +61,8 @@ default byte getByte(int position)
 
     /**
      * Gets a short in the value at {@code position}.
+     *
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default short getShort(int position)
     {
@@ -67,6 +71,8 @@ default short getShort(int position)
 
     /**
      * Gets an int in the value at {@code position}.
+     *
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default int getInt(int position)
     {
@@ -75,6 +81,8 @@ default int getInt(int position)
 
     /**
      * Gets a long in the value at {@code position}.
+     *
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default long getLong(int position)
     {
@@ -99,15 +107,16 @@ default Slice getSlice(int position, int offset, int length)
 
     /**
      * Gets a block in the value at {@code position}.
-     * @return
+     *
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default Block getBlock(int position)
     {
         throw new UnsupportedOperationException(getClass().getName());
     }
 
     /**
-     * Is the byte sequences at {@code offset} in the value at {@code position} equal
+     * Is the byte sequence at {@code offset} in the value at {@code position} equal
      * to the byte sequence at {@code otherOffset} in {@code otherSlice}.
      * This method must be implemented if @{code getSlice} is implemented.
      */
@@ -147,7 +156,7 @@ default void writeBytesTo(int position, int offset, int length, SliceOutput slic
     }
 
     /**
-     * Appends the value at {@code position} to {@code blockBuilder} and close the entry.
+     * Appends the value at {@code position} to {@code blockBuilder} and closes the entry.
      */
     void writePositionTo(int position, BlockBuilder blockBuilder);
 
@@ -378,12 +387,14 @@ default Block getLoadedBlock()
     Block appendNull();
 
     /**
-     * Returns the converted long value at {@code position} if the value ar {@code position} can be converted to long.
-     * @throws UnsupportedOperationException if value at {@code position} is not compatible to be converted to long.
+     * Returns the converted long value at {@code position} if the value at {@code position} can be converted to long.
      *
      * Difference between toLong() and getLong() is:
      * getLong() would only return value when the block is LongArrayBlock, otherwise it would throw exception.
      * toLong() would return value for compatible types: LongArrayBlock, IntArrayBlock, ByteArrayBlock and ShortArrayBlock.
+     *
+     * @throws UnsupportedOperationException if value at {@code position} is not able to be converted to long.
+     * @throws IllegalArgumentException if position is negative or greater than or equal to the positionCount
      */
     default long toLong(int position)
     {

presto-common/src/main/java/com/facebook/presto/common/block/DictionaryBlock.java

@@ -36,6 +36,20 @@
 import static java.lang.String.format;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * A dictionary holds positionCount values of arbitrary types. Usually some of these values are repeated,
+ * and the block wraps an underlying delegate block with fewer or no repeated values.
+ * This delegate block is called the "dictionary".
+ * The ids array contains positionCount indexes into the underlying delegate block.
+ * When value N is requested from this block instead of returning the value directly,
+ * it looks up the index of value N at ids[N]; then it returns the value in dictionary[ids[N]].
+ * This compresses data when the same value repeats at multiple locations.
+ *
+ * Not every id in the ids array is a valid position in the block.
+ * Specify an offset in the ids array to indicate that IDs are only stored from that position forward.
+ * If the ids array is longer than offset+positionCount, then extra values to the right are not valid.
+ * That is, IDs are stored in a range of the array from offset to offset+positionCount-1 (inclusive).
+ */
 public class DictionaryBlock
         implements Block
 {
@@ -509,6 +523,10 @@ int[] getRawIds()
         return ids;
     }
 
+    /**
+     * @param position the position of the desired value in this block
+     * @return the position of the desired value in the underlying block this block wraps
+     */
     public int getId(int position)
     {
         checkValidPosition(position, positionCount);