Working on the documentation of core classes.

withdraw some of the goodness I banked a while ago with the AnyVal
types. Started on what will culminate in the total elimination of
SourcelessComments. Cleaned up the docs on ancient classes like Product.
More to come. No review.

1 files changed, 19 insertions, 17 deletions

diff --git a/src/library/scala/Product.scala b/src/library/scala/Product.scala
index 786be5ec13..dfa04bbbe7 100644
--- a/src/library/scala/Product.scala
+++ b/src/library/scala/Product.scala
@@ -8,30 +8,33 @@
 
 package scala
 
-/** Base trait for all products.  See [[scala.Product2]].
+/** Base trait for all products, which in the standard library include at least
+ *  [[scala.Product1]] through [[scala.Product22]] and therefore also their
+ *  subclasses [[scala.Tuple1]] through [[scala.Tuple22]].  In addition, all case
+ *  classes implement Product with synthetically generated methods.
  *
  *  @author  Burak Emir
  *  @version 1.0
  *  @since   2.3
  */
 trait Product extends Equals {
-
-  /** Returns the nth element of this product, 0-based.  In other words, for a
-   * product <code>A(x_1,...,x_k)</code>, returns <code>x_(n+1)</code>
-   * where <code>0 &lt;= n &lt; k</code>
+  /** The nth element of this product, 0-based.  In other words, for a
+   *  product `A(x_1, ..., x_k)`, returns x_(n+1) where 0 < n < k.
    *
-   *  @param  n the index of the element to return
-   *  @throws IndexOutOfBoundsException
-   *  @return  The element <code>n</code> elements after the first element
+   *  @param    n   the index of the element to return
+   *  @throws       IndexOutOfBoundsException
+   *  @return       the element `n` elements after the first element
    */
   def productElement(n: Int): Any
 
-  /** Returns the size of this product.
-   * @return For a product <code>A(x_1,...,x_k)</code>, returns `k`
+  /** The size of this product.
+   *  @return     for a product `A(x_1, ..., x_k)`, returns `k`
    */
   def productArity: Int
 
-  /** An iterator that returns all fields of this product */
+  /** An iterator over all the elements of this product.
+   *  @return     in the default implementation, an Iterator[Any]
+   */
   def productIterator: Iterator[Any] = new Iterator[Any] {
     private var c: Int = 0
     private val cmax = productArity
@@ -42,12 +45,11 @@ trait Product extends Equals {
   @deprecated("use productIterator instead")
   def productElements: Iterator[Any] = productIterator
 
-  /**
-   * Returns a string that is used in the `toString` method of subtraits/classes.
-   *  Implementations may override this
-   *  method in order to prepend a string prefix to the result of the
-   *  toString methods.
-   *  @return the empty string
+  /** A string used in the `toString` methods of derived classes.
+   *  Implementations may override this method to prepend a string prefix
+   *  to the result of toString methods.
+   *
+   *  @return   in the default implementation, the empty string
    */
   def productPrefix = ""
 }