fix scaladoc list syntax, add docs for some rules

src/main/scala/catalyst/analysis/typeCoercion.scala

@@ -43,11 +43,11 @@ object ConvertNaNs extends Rule[LogicalPlan] {
  * Loosely based on rules from "Hadoop: The Definitive Guide" 2nd edition, by Tom White
  *
  * The implicit conversion rules can be summarized as follows:
- * $ - Any integral numeric type can be implicitly converted to a wider type.
- * $ - All the integral numeric types, FLOAT, and (perhaps surprisingly) STRING can be implicitly
+ *   - Any integral numeric type can be implicitly converted to a wider type.
+ *   - All the integral numeric types, FLOAT, and (perhaps surprisingly) STRING can be implicitly
  *     converted to DOUBLE.
- * $ - TINYINT, SMALLINT, and INT can all be converted to FLOAT.
- * $ - BOOLEAN types cannot be converted to any other type.
+ *   - TINYINT, SMALLINT, and INT can all be converted to FLOAT.
+ *   - BOOLEAN types cannot be converted to any other type.
  *
  * String conversions are handled by the PromoteStrings rule.
  */

src/main/scala/catalyst/expressions/Expression.scala

@@ -9,13 +9,14 @@ abstract class Expression extends TreeNode[Expression] {
 
   def dataType: DataType
   /**
-   * foldable is used to indicate if an expression can be folded.
-   * Right now, we consider expressions listed below as foldable expressions.
-   * - A Coalesce is foldable if all of its children are foldable
-   * - A BinaryExpression is foldable if its both left and right child are foldable.
-   * - A Not, isNull, or isNotNull is foldable if its child is foldable.
-   * - A Literal is foldable.
-   * - A Cast or UnaryMinus is foldable if its child is foldable.
+   * Returns true when an expression is a candidate for static evaluation before the query is
+   * executed.
+   * The following conditions are used to determine suitability for constant folding:
+   *  - A Coalesce is foldable if all of its children are foldable
+   *  - A BinaryExpression is foldable if its both left and right child are foldable.
+   *  - A Not, isNull, or isNotNull is foldable if its child is foldable.
+   *  - A Literal is foldable.
+   *  - A Cast or UnaryMinus is foldable if its child is foldable.
    */
   // TODO: Supporting more foldable expressions. For example, deterministic Hive UDFs.
   def foldable: Boolean = false

src/main/scala/catalyst/optimizer/Optimizer.scala

@@ -12,7 +12,7 @@ object Optimize extends RuleExecutor[LogicalPlan] {
       EliminateSubqueries) ::
     Batch("ConstantFolding", Once,
       ConstantFolding,
-      BooleanSimplification
+      BooleanSimplification
     ) :: Nil
 }
 
@@ -26,6 +26,10 @@ object EliminateSubqueries extends Rule[LogicalPlan] {
   }
 }
 
+/**
+ * Replaces expressions that can be statically evaluated with equivalent [[expressions.Literal]]
+ * values.
+ */
 object ConstantFolding extends Rule[LogicalPlan] {
   def apply(plan: LogicalPlan): LogicalPlan = plan transform {
     case q: LogicalPlan => q transformExpressionsDown {
@@ -34,7 +38,12 @@ object ConstantFolding extends Rule[LogicalPlan] {
   }
 }
 
-object BooleanSimplification extends Rule[LogicalPlan] {
+/**
+ * Simplifies boolean expressions where the answer can be determined without evaluating both sides.
+ * Note that this rule can eliminate expressions that might otherwise have been evaluated and thus
+ * is only safe when evaluations of expressions does not result in side effects.
+ */
+object BooleanSimplification extends Rule[LogicalPlan] {
   def apply(plan: LogicalPlan): LogicalPlan = plan transform {
     case q: LogicalPlan => q transformExpressionsUp {
       case and @ And(left, right) => {