[SQL][minor] Improved Row documentation.

Author: Reynold Xin <rxin@databricks.com>

Closes #4085 from rxin/row-doc and squashes the following commits:

f77cb27 [Reynold Xin] [SQL][minor] Improved Row documentation.

1 files changed, 114 insertions, 52 deletions

diff --git a/sql/catalyst/src/main/scala/org/apache/spark/sql/Row.scala b/sql/catalyst/src/main/scala/org/apache/spark/sql/Row.scala
index d7a4e014ce..a28a1e90dd 100644
--- a/sql/catalyst/src/main/scala/org/apache/spark/sql/Row.scala
+++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/Row.scala
@@ -91,26 +91,6 @@ object Row {
  * // isNull: Boolean = true
  * }}}
  *
- * Interfaces related to native primitive access are:
- *
- * `isNullAt(i: Int): Boolean`
- *
- * `getInt(i: Int): Int`
- *
- * `getLong(i: Int): Long`
- *
- * `getDouble(i: Int): Double`
- *
- * `getFloat(i: Int): Float`
- *
- * `getBoolean(i: Int): Boolean`
- *
- * `getShort(i: Int): Short`
- *
- * `getByte(i: Int): Byte`
- *
- * `getString(i: Int): String`
- *
  * In Scala, fields in a [[Row]] object can be extracted in a pattern match. Example:
  * {{{
  * import org.apache.spark.sql._
@@ -124,99 +104,181 @@ object Row {
  * @group row
  */
 trait Row extends Seq[Any] with Serializable {
+  /**
+   * Returns the value at position i. If the value is null, null is returned. The following
+   * is a mapping between Spark SQL types and return types:
+   *
+   * {{{
+   *   BooleanType -> java.lang.Boolean
+   *   ByteType -> java.lang.Byte
+   *   ShortType -> java.lang.Short
+   *   IntegerType -> java.lang.Integer
+   *   FloatType -> java.lang.Float
+   *   DoubleType -> java.lang.Double
+   *   StringType -> String
+   *   DecimalType -> scala.math.BigDecimal
+   *
+   *   DateType -> java.sql.Date
+   *   TimestampType -> java.sql.Timestamp
+   *
+   *   BinaryType -> byte array
+   *   ArrayType -> scala.collection.Seq (use getList for java.util.List)
+   *   MapType -> scala.collection.Map (use getJavaMap for java.util.Map)
+   *   StructType -> org.apache.spark.sql.Row
+   * }}}
+   */
   def apply(i: Int): Any
 
-  /** Returns the value at position i. If the value is null, null is returned. */
+  /**
+   * Returns the value at position i. If the value is null, null is returned. The following
+   * is a mapping between Spark SQL types and return types:
+   *
+   * {{{
+   *   BooleanType -> java.lang.Boolean
+   *   ByteType -> java.lang.Byte
+   *   ShortType -> java.lang.Short
+   *   IntegerType -> java.lang.Integer
+   *   FloatType -> java.lang.Float
+   *   DoubleType -> java.lang.Double
+   *   StringType -> String
+   *   DecimalType -> scala.math.BigDecimal
+   *
+   *   DateType -> java.sql.Date
+   *   TimestampType -> java.sql.Timestamp
+   *
+   *   BinaryType -> byte array
+   *   ArrayType -> scala.collection.Seq (use getList for java.util.List)
+   *   MapType -> scala.collection.Map (use getJavaMap for java.util.Map)
+   *   StructType -> org.apache.spark.sql.Row
+   * }}}
+   */
   def get(i: Int): Any = apply(i)
 
   /** Checks whether the value at position i is null. */
   def isNullAt(i: Int): Boolean
 
   /**
+   * Returns the value at position i as a primitive boolean.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
+   */
+  def getBoolean(i: Int): Boolean
+
+  /**
+   * Returns the value at position i as a primitive byte.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
+   */
+  def getByte(i: Int): Byte
+
+  /**
+   * Returns the value at position i as a primitive short.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
+   */
+  def getShort(i: Int): Short
+
+  /**
    * Returns the value at position i as a primitive int.
-   * Throws an exception if the type mismatches or if the value is null.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
    */
   def getInt(i: Int): Int
 
   /**
    * Returns the value at position i as a primitive long.
-   * Throws an exception if the type mismatches or if the value is null.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
    */
   def getLong(i: Int): Long
 
   /**
-   * Returns the value at position i as a primitive double.
-   * Throws an exception if the type mismatches or if the value is null.
-   */
-  def getDouble(i: Int): Double
-
-  /**
    * Returns the value at position i as a primitive float.
    * Throws an exception if the type mismatches or if the value is null.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
    */
   def getFloat(i: Int): Float
 
   /**
-   * Returns the value at position i as a primitive boolean.
-   * Throws an exception if the type mismatches or if the value is null.
+   * Returns the value at position i as a primitive double.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
    */
-  def getBoolean(i: Int): Boolean
+  def getDouble(i: Int): Double
 
   /**
-   * Returns the value at position i as a primitive short.
-   * Throws an exception if the type mismatches or if the value is null.
+   * Returns the value at position i as a String object.
+   *
+   * @throws ClassCastException when data type does not match.
+   * @throws NullPointerException when value is null.
    */
-  def getShort(i: Int): Short
+  def getString(i: Int): String
 
   /**
-   * Returns the value at position i as a primitive byte.
-   * Throws an exception if the type mismatches or if the value is null.
+   * Returns the value at position i of decimal type as java.math.BigDecimal.
+   *
+   * @throws ClassCastException when data type does not match.
    */
-  def getByte(i: Int): Byte
+  def getDecimal(i: Int): BigDecimal = apply(i).asInstanceOf[BigDecimal]
 
   /**
-   * Returns the value at position i as a String object.
-   * Throws an exception if the type mismatches or if the value is null.
+   * Returns the value at position i of date type as java.sql.Date.
+   *
+   * @throws ClassCastException when data type does not match.
    */
-  def getString(i: Int): String
+  def getDate(i: Int): java.sql.Date = apply(i).asInstanceOf[java.sql.Date]
 
   /**
-   * Return the value at position i of array type as a Scala Seq.
-   * Throws an exception if the type mismatches.
+   * Returns the value at position i of array type as a Scala Seq.
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getSeq[T](i: Int): Seq[T] = apply(i).asInstanceOf[Seq[T]]
 
   /**
-   * Return the value at position i of array type as [[java.util.List]].
-   * Throws an exception if the type mismatches.
+   * Returns the value at position i of array type as [[java.util.List]].
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getList[T](i: Int): java.util.List[T] = {
     scala.collection.JavaConversions.seqAsJavaList(getSeq[T](i))
   }
 
   /**
-   * Return the value at position i of map type as a Scala Map.
-   * Throws an exception if the type mismatches.
+   * Returns the value at position i of map type as a Scala Map.
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getMap[K, V](i: Int): scala.collection.Map[K, V] = apply(i).asInstanceOf[Map[K, V]]
 
   /**
-   * Return the value at position i of array type as a [[java.util.Map]].
-   * Throws an exception if the type mismatches.
+   * Returns the value at position i of array type as a [[java.util.Map]].
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getJavaMap[K, V](i: Int): java.util.Map[K, V] = {
     scala.collection.JavaConversions.mapAsJavaMap(getMap[K, V](i))
   }
 
   /**
-   * Return the value at position i of struct type as an [[Row]] object.
-   * Throws an exception if the type mismatches.
+   * Returns the value at position i of struct type as an [[Row]] object.
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getStruct(i: Int): Row = getAs[Row](i)
 
   /**
    * Returns the value at position i.
-   * Throws an exception if the type mismatches.
+   *
+   * @throws ClassCastException when data type does not match.
    */
   def getAs[T](i: Int): T = apply(i).asInstanceOf[T]