debuginfo: Add documentation comments to debuginfo.rs

Conflicts:
	src/librustc/middle/trans/debuginfo.rs
debuginfo: Make DWARF representation of enums uniform.

So far the DWARF information for enums was different
for regular enums, univariant enums, Option-like enums,
etc. Regular enums were encoded as unions of structs,
while the other variants were encoded as bare structs.

With the changes in this PR all enums are encoded as
unions so that debuggers can reconstruct if something
originally was a struct, a univariant enum, or an
Option-like enum. For the latter case, information
about the Null variant is encoded into the union field
name. This information can then be used by the
debugger to print a None value actually as None
instead of Some(0x0).
auto merge of #14486 : michaelwoerister/rust/unified_enum_rep, r=luqmana

So far the DWARF information for enums was different for regular enums, univariant enums, Option-like enums, etc. Regular enums were encoded as unions of structs, while the other variants were encoded as bare structs. With the changes in this PR all enums are encoded as unions so that debuggers can reconstruct if something originally was a struct, a univariant enum, or an Option-like enum.  For the latter case, information about the *Null* variant is encoded into the union field name. This information can then be used by the debugger to print a `None` value actually as `None` instead of `Some(0x0)`.

The changes in this PR should also fix the regression reported in #14385 and #14411, but I want to close these only after I have confirmation from the original reporters that the issues are actually fixed for them.
std: Recreate a `rand` module

This commit shuffles around some of the `rand` code, along with some
reorganization. The new state of the world is as follows:

* The librand crate now only depends on libcore. This interface is experimental.
* The standard library has a new module, `std::rand`. This interface will
  eventually become stable.

Unfortunately, this entailed more of a breaking change than just shuffling some
names around. The following breaking changes were made to the rand library:

* Rng::gen_vec() was removed. This has been replaced with Rng::gen_iter() which
  will return an infinite stream of random values. Previous behavior can be
  regained with `rng.gen_iter().take(n).collect()`

* Rng::gen_ascii_str() was removed. This has been replaced with
  Rng::gen_ascii_chars() which will return an infinite stream of random ascii
  characters. Similarly to gen_iter(), previous behavior can be emulated with
  `rng.gen_ascii_chars().take(n).collect()`

* {IsaacRng, Isaac64Rng, XorShiftRng}::new() have all been removed. These all
  relied on being able to use an OSRng for seeding, but this is no longer
  available in librand (where these types are defined). To retain the same
  functionality, these types now implement the `Rand` trait so they can be
  generated with a random seed from another random number generator. This allows
  the stdlib to use an OSRng to create seeded instances of these RNGs.

* Rand implementations for `Box<T>` and `@T` were removed. These seemed to be
  pretty rare in the codebase, and it allows for librand to not depend on
  liballoc.  Additionally, other pointer types like Rc<T> and Arc<T> were not
  supported.  If this is undesirable, librand can depend on liballoc and regain
  these implementations.

* The WeightedChoice structure is no longer built with a `Vec<Weighted<T>>`,
  but rather a `&mut [Weighted<T>]`. This means that the WeightedChoice
  structure now has a lifetime associated with it.

* The `sample` method on `Rng` has been moved to a top-level function in the
  `rand` module due to its dependence on `Vec`.

cc #13851

[breaking-change]
auto merge of #14427 : alexcrichton/rust/librand, r=huonw

This commit shuffles around some of the `rand` code, along with some
reorganization. The new state of the world is as follows:

* The librand crate now only depends on libcore. This interface is experimental.
* The standard library has a new module, `std::rand`. This interface will
  eventually become stable.

Unfortunately, this entailed more of a breaking change than just shuffling some
names around. The following breaking changes were made to the rand library:

* Rng::gen_vec() was removed. This has been replaced with Rng::gen_iter() which
  will return an infinite stream of random values. Previous behavior can be
  regained with `rng.gen_iter().take(n).collect()`

* Rng::gen_ascii_str() was removed. This has been replaced with
  Rng::gen_ascii_chars() which will return an infinite stream of random ascii
  characters. Similarly to gen_iter(), previous behavior can be emulated with
  `rng.gen_ascii_chars().take(n).collect()`

* {IsaacRng, Isaac64Rng, XorShiftRng}::new() have all been removed. These all
  relied on being able to use an OSRng for seeding, but this is no longer
  available in librand (where these types are defined). To retain the same
  functionality, these types now implement the `Rand` trait so they can be
  generated with a random seed from another random number generator. This allows
  the stdlib to use an OSRng to create seeded instances of these RNGs.

* Rand implementations for `Box<T>` and `@T` were removed. These seemed to be
  pretty rare in the codebase, and it allows for libcore to not depend on
  liballoc.  Additionally, other pointer types like Rc<T> and Arc<T> were not
  supported.  If this is undesirable, librand can depend on liballoc and regain
  these implementations.

* The WeightedChoice structure is no longer built with a `Vec<Weighted<T>>`,
   but rather a `&mut [Weighted<T>]`. This means that the WeightedChoice
   structure now has a lifetime associated with it.

cc #13851

[breaking-change]