Update the ScalaDoc of js.Any, js.UndefOr and the js package object.

With the introduction of js.| and Scala.js-defined JS classes,
those ScalaDocs were outdated.

Author: sjrd

library/src/main/scala/scala/scalajs/js/Any.scala

@@ -21,15 +21,28 @@ import scala.collection.generic.CanBuildFrom
 
 import annotation.ScalaJSDefined
 
-/** Supertype of all JavaScript values.
+/** Root of the hierarchy of JavaScript types.
  *
- *  Subtypes of [[Any js.Any]] are facade types to APIs implemented in
- *  JavaScript code. Their implementation is irrelevant and never emitted.
- *  As such, all members must be defined with their right-hand-side being
- *  [[native js.native]].
+ *  Subtypes of [[Any js.Any]] are JavaScript types, which have different
+ *  semantics and guarantees than Scala types (subtypes of [[AnyRef]] and
+ *  [[AnyVal]]). Operations on JavaScript types behave as the corresponding
+ *  operations in the JavaScript language.
  *
- *  In most cases, you should extend [[Object js.Object]] instead of this
- *  trait to define facade types.
+ *  By default, JavaScript types are native: they are facade types to APIs
+ *  implemented in JavaScript code. Their implementation is irrelevant and
+ *  never emitted. As such, all members must be defined with their
+ *  right-hand-side being [[native js.native]]. For forward source
+ *  compatibility with the next major version, the class/trait/object itself
+ *  should be annotated with [[native @js.native]].
+ *
+ *  In most cases, you should not directly extend this trait, but rather extend
+ *  [[Object js.Object]].
+ *
+ *  To implement a JavaScript type in Scala.js (therefore non-native), its
+ *  declaration must be annotated with
+ *  [[annotation.ScalaJSDefined @ScalaJSDefined]]. Scala.js-defined JS types
+ *  cannot directly extend native JS traits; and Scala.js-defined JS traits
+ *  cannot declare concrete term members.
  *
  *  It is not possible to define traits or classes that inherit both from this
  *  trait and a strict subtype of [[AnyRef]]. In fact, you should think of

library/src/main/scala/scala/scalajs/js/UndefOr.scala

@@ -12,14 +12,13 @@ package scala.scalajs.js
 import scala.language.implicitConversions
 
 /** Value of type A or the JS undefined value.
- *  In a type system with union types, this would really be
- *  `A | js.prim.Undefined`. Since Scala does not have union types, but this
- *  particular union is crucial to many interoperability scenarios, it is
- *  provided as this trait.
  *
- *  An API similar to that of [[scala.Option]] is provided through the
- *  [[UndefOrOps]] implicit class, with the understanding that `undefined` is
- *  the None value.
+ *  `js.UndefOr[A]` is the type of a value that can be either `undefined` or
+ *  an `A`. It provides an API similar to that of [[scala.Option]] through the
+ *  [[UndefOrOps]] implicit class, where `undefined` take the role of [[None]].
+ *
+ *  By extension, this type is also suited to typing optional fields in native
+ *  JS types, i.e., fields that may not exist on the object.
  */
 @scala.scalajs.js.annotation.RawJSType // Don't do this at home!
 sealed trait UndefOr[+A]
@@ -231,7 +230,7 @@ final class UndefOrOps[A](val self: UndefOr[A]) extends AnyVal {
   @inline final def toLeft[X](right: => X): Either[A, X] =
     if (isEmpty) Right(right) else Left(this.forceGet)
 
-  /** Returns a [[scala.Some]] containing this $options's value
+  /** Returns a [[scala.Some]] containing this $option's value
    *  if this $option is nonempty, [[scala.None]] otherwise.
    */
   @inline final def toOption: Option[A] =

library/src/main/scala/scala/scalajs/js/package.scala

@@ -22,32 +22,25 @@ package scala.scalajs
  *
  *  == Overview ==
  *
- *  The trait [[js.Any]] is the super type of all JavaScript values.
- *
- *  All class, trait and object definitions that inherit, directly or
- *  indirectly, from [[js.Any]] do not have actual implementations in Scala.
- *  They are only the manifestation of static types representing libraries
- *  written directly in JavaScript. It is not possible to implement yourself
- *  a subclass of [[js.Any]]: all the method definitions will be ignored when
- *  compiling to JavaScript.
+ *  The trait [[js.Any]] is the root of the hierarchy of JavaScript types.
+ *  This package defines important subtypes of [[js.Any]] that are defined
+ *  in the standard library of ECMAScript 5.1 (or ES 6, with a label in the
+ *  documentation), such as [[Object js.Object]], [[Array js.Array]] and
+ *  [[RegExp js.RegExp]].
  *
  *  Implicit conversions to and from standard Scala types to their equivalent
  *  in JavaScript are provided. For example, from Scala functions to JavaScript
  *  functions and back.
  *
- *  The most important subclasses of [[js.Any]] are:
- *  - [[js.Dynamic]], a dynamically typed interface to JavaScript APIs
- *  - [[js.Object]], the superclass of all statically typed JavaScript classes,
- *    which has subclasses for all the classes standardized in ECMAScript 5.1,
- *    among which:
- *    - [[js.Array]]
- *    - [[js.Function]] (and subtraits with specific number of parameters)
- *    - [[js.ThisFunction]] and its subtraits for functions that take the
- *      JavaScript `this` as an explicit parameters
- *    - [[js.Dictionary]] to access the properties of an object in a
- *      dictionary-like way
- *    - [[js.Date]]
- *    - [[js.RegExp]]
+ *  The most important subtypes of [[js.Any]] declared in this package are:
+ *  - [[Object js.Object]], the superclass of most (all) JavaScript classes
+ *  - [[Array js.Array]]
+ *  - [[Function js.Function]] (and subtraits with specific number of
+ *    parameters)
+ *  - [[ThisFunction js.ThisFunction]] and its subtraits for functions that
+ *    take the JavaScript `this` as an explicit parameter
+ *  - [[Dictionary js.Dictionary]], a [[Map]]-like view of the properties of a
+ *    JS object
  *
  *  The trait [[js.Dynamic]] is a special subtrait of [[js.Any]]. It can
  *  represent any JavaScript value in a dynamically-typed way. It is possible
@@ -56,14 +49,17 @@ package scala.scalajs
  *
  *  There are no explicit definitions for JavaScript primitive types, as one
  *  could expect, because the corresponding Scala types stand in their stead:
- *  - [[Boolean]] is a primitive JavaScript boolean
- *  - [[Double]] is a primitive JavaScript number
- *  - [[String]] is a primitive JavaScript string
+ *  - [[Boolean]] is the type of primitive JavaScript booleans
+ *  - [[Double]] is the type of primitive JavaScript numbers
+ *  - [[String]] is the type of primitive JavaScript strings (or `null`)
  *  - [[Unit]] is the type of the JavaScript undefined value
  *  - [[Null]] is the type of the JavaScript null value
  *
- *  [[js.UndefOr]] gives a [[scala.Option]]-like interface where the JavaScript
- *  value `undefined` takes the role of `None`.
+ *  [[UndefOr js.UndefOr]] gives a [[scala.Option]]-like interface where the
+ *  JavaScript value `undefined` takes the role of `None`.
+ *
+ *  [[| A | B]] is an unboxed pseudo-union type, suitable to type values that
+ *  admit several unrelated types in facade types.
  */
 package object js {
   /** The undefined value. */