SPARK-3580: New public method for RDD's to have consistent way of obtain...

...ing the number of RDD partitions across languages.


Including a (pretty obvious) spark-shell example in the scaladoc of a simple RDD method isn't really consistent with the rest of the RDD API documentation.