SPARK-1628 follow up: Improve RangePartitioner's documentation.

Adding a paragraph clarifying a weird behavior in RangePartitioner.

See also #549.

Author: Reynold Xin <rxin@apache.org>

Closes #1012 from rxin/partitioner-doc and squashes the following commits:

6f0109e [Reynold Xin] SPARK-1628 follow up: Improve RangePartitioner's documentation.

core/src/main/scala/org/apache/spark/Partitioner.scala

@@ -90,6 +90,10 @@ class HashPartitioner(partitions: Int) extends Partitioner {
 /**
  * A [[org.apache.spark.Partitioner]] that partitions sortable records by range into roughly
  * equal ranges. The ranges are determined by sampling the content of the RDD passed in.
+ *
+ * Note that the actual number of partitions created by the RangePartitioner might not be the same
+ * as the `partitions` parameter, in the case where the number of sampled records is less than
+ * the value of `partitions`.
  */
 class RangePartitioner[K : Ordering : ClassTag, V](
     partitions: Int,
@@ -158,7 +162,6 @@ class RangePartitioner[K : Ordering : ClassTag, V](
       false
   }
 
-
   override def hashCode(): Int = {
     val prime = 31
     var result = 1