Improved API documentation for scala.compat.Pla...

Improved API documentation for scala.compat.Platform. Contributed by
Matthew Farwell during the September doc spree.

1 files changed, 68 insertions, 8 deletions

diff --git a/src/library/scala/compat/Platform.scala b/src/library/scala/compat/Platform.scala
index 8ee356e95f..f18ce12e6c 100644
--- a/src/library/scala/compat/Platform.scala
+++ b/src/library/scala/compat/Platform.scala
@@ -14,13 +14,25 @@ import java.lang.System
 
 object Platform {
 
+  /** Thrown when a stack overflow occurs because a method or function recurses too deeply.
+    *
+    * On the JVM, this is a type alias for `java.lang.StackOverflowError`, which itself extends `java.lang.Error`.
+    * The same rules apply to catching a `java.lang.Error` as for Java, that it indicates a serious problem that a reasonable application should not try and catch.
+    */
   type StackOverflowError = java.lang.StackOverflowError
+
+  /** This is a type alias for `java.util.ConcurrentModificationException`,
+    * which may be thrown by methods that detect an invalid modification of an object.
+    * For example, many common collection types do not allow modifying a collection
+    * while it is being iterated over.
+    */
   type ConcurrentModificationException = java.util.ConcurrentModificationException
 
   /** Copies `length` elements of array `src` starting at position `srcPos` to the
-    * array `dest` starting at position `destPos`. If `src eq dest`, the copying will
+    * array `dest` starting at position `destPos`. If `src`==`dest`, the copying will
     * behave as if the elements copied from `src` were first copied to a temporary
     * array before being copied back into the array at the destination positions.
+    *
     * @param src     A non-null array as source for the copy.
     * @param srcPos  The starting index in the source array.
     * @param dest    A non-null array as destination for the copy.
@@ -33,39 +45,87 @@ object Platform {
     * @throws java.lang.IndexOutOfBoundsException If either srcPos` or `destPos` are
     *                outside of the bounds of their respective arrays; or if `length`
     *                is negative; or if there are less than `length` elements available
-    *                after `srcPos` or `destPos` in `src` and `dest` respectively. */
+    *                after `srcPos` or `destPos` in `src` and `dest` respectively.
+    */
   @inline
   def arraycopy(src: AnyRef, srcPos: Int, dest: AnyRef, destPos: Int, length: Int) {
     System.arraycopy(src, srcPos, dest, destPos, length)
   }
 
-  /** Create array of the same type as arrayInstance with the given
-   *  length.
+  /** Creates a new array of the specified type and given length.
+   *
+   *  Note that if `elemClass` is a subclass of [[scala.AnyVal]] then the returned value is an Array of the corresponding java primitive type.
+   *  For example, the following code `scala.compat.Platform.createArray(classOf[Int], 4)` returns an array of the java primitive type `int`.
+   *
+   *  For a [[scala.AnyVal]] array, the values of the array are set to 0 for ''numeric value types'' ([[scala.Double]], [[scala.Float]], [[scala.Long]], [[scala.Int]], [[scala.Char]],
+   *  [[scala.Short]], and [[scala.Byte]]), and `false` for [[scala.Boolean]]. Creation of an array of type [[scala.Unit]] is not possible.
+   *
+   *  For subclasses of [[scala.AnyRef]], the values of the array are set to `null`.
+   *
+   *  The caller must cast the returned value to the correct type.
+   *
+   *  @example {{{
+   *  val a = scala.compat.Platform.createArray(classOf[Int], 4).asInstanceOf[Array[Int]] // returns Array[Int](0, 0, 0, 0)
+   *  }}}
    *
-   *  @param elemClass ..
-   *  @param length    ..
-   *  @return          ..
+   *  @param elemClass the `Class` object of the component type of the array
+   *  @param length    the length of the new array.
+   *  @return          an array of the given component type as an `AnyRef`.
+   *  @throws `java.lang.NullPointerException` If `elemClass` is `null`.
+   *  @throws `java.lang.IllegalArgumentException` if componentType is [[scala.Unit]] or `java.lang.Void.TYPE`
+   *  @throws `java.lang.NegativeArraySizeException` if the specified length is negative
    */
   @inline
   def createArray(elemClass: Class[_], length: Int): AnyRef =
     java.lang.reflect.Array.newInstance(elemClass, length)
 
+  /** Assigns the value of 0 to each element in the array.
+    * @param arr     A non-null Array[Int].
+    * @throws `java.lang.NullPointerException` If `arr` is `null`.
+    */
   @inline
   def arrayclear(arr: Array[Int]) { java.util.Arrays.fill(arr, 0) }
 
+  /** Returns the `Class` object associated with the class or interface with the given string name using the current `ClassLoader`.
+   *  On the JVM, invoking this method is equivalent to: `java.lang.Class.forName(name)`
+   *
+   *  For more information, please see the Java documentation for [[java.lang.Class]].
+   *
+   * @param    name the fully qualified name of the desired class.
+   * @return   the `Class` object for the class with the specified name.
+   * @throws `java.lang.LinkageError` if the linkage fails
+   * @throws `java.lang.ExceptionInInitializerError` if the initialization provoked by this method fails
+   * @throws `java.lang.ClassNotFoundException` if the class cannot be located
+   *  @example {{{
+   *  val a = scala.compat.Platform.getClassForName("java.lang.Integer")  // returns the Class[_] for java.lang.Integer
+   *  }}}
+   */
   @inline
   def getClassForName(name: String): Class[_] = java.lang.Class.forName(name)
 
+  /** The default line separator.
+   *
+   * On the JVM, this is equivalent to calling the method:
+   * `System.getProperty("line.separator")`
+   * with a default value of "\n".
+   */
   val EOL = util.Properties.lineSeparator
 
   /** The current time in milliseconds. The time is counted since 1 January 1970
     * UTC.
     *
     * Note that the operating system timer used to obtain this value may be less
-    * precise than a millisecond. */
+    * precise than a millisecond.
+    */
   @inline
   def currentTime: Long = System.currentTimeMillis()
 
+  /** Runs the garbage collector.
+   *
+   * This is a request that the underlying JVM runs the garbage collector.
+   * The results of this call depends heavily on the JVM used.
+   * The underlying JVM is free to ignore this request.
+   */
   @inline
   def collectGarbage(): Unit = System.gc()