[SPARK-21213][SQL] improved comments per review feedback

sql/core/src/main/scala/org/apache/spark/sql/execution/SparkSqlParser.scala

@@ -91,17 +91,17 @@ class SparkSqlAstBuilder(conf: SQLConf) extends AstBuilder(conf) {
 
   /**
    * Create an [[AnalyzeTableCommand]] command or an [[AnalyzeColumnCommand]] command.
-   * Example SQL for analyzing table :
+   * Example SQL for analyzing table or a single partition :
    * {{{
-   *   ANALYZE TABLE table COMPUTE STATISTICS [NOSCAN];
-   * }}}
-   * Example SQL for analyzing a single partition :
-   * {{{
-   *   ANALYZE TABLE table PARTITION (key=value,..) COMPUTE STATISTICS [NOSCAN];
+   *   ANALYZE TABLE [db_name.]tablename [PARTITION (parcol1=val1, partcol2=val2, ...)]
+   *   COMPUTE STATISTICS [NOSCAN];
    * }}}
+   * Partitions spec, if provided, must identify a single partition by specifying values
+   * for all partition columns.
+   *
    * Example SQL for analyzing columns :
    * {{{
-   *   ANALYZE TABLE table COMPUTE STATISTICS FOR COLUMNS column1, column2;
+   *   ANALYZE TABLE [db_name.]tablename COMPUTE STATISTICS FOR COLUMNS column1, column2;
    * }}}
    */
   override def visitAnalyze(ctx: AnalyzeContext): LogicalPlan = withOrigin(ctx) {

sql/core/src/main/scala/org/apache/spark/sql/execution/command/AnalyzeTableCommand.scala

@@ -30,6 +30,9 @@ import org.apache.spark.sql.catalyst.expressions.{And, EqualTo, Expression, Lite
  * query optimizations.
  *
  * If certain partition spec is specified, then statistics are gathered for only that partition.
+ * Partition spec must identify a single partition by specifying values for all partition columns.
+ *
+ * TODO Support a range of partitions by allowing partial partition specs
  */
 case class AnalyzeTableCommand(
     tableIdent: TableIdentifier,