auto merge of #14668 : aochagavia/rust/pr3, r=alexcrichton

Closes https://github.com/mozilla/rust/issues/14577
Closes https://github.com/mozilla/rust/issues/14639

src/libcollections/vec.rs

@@ -782,11 +782,11 @@ impl<T> Vec<T> {
         self.as_mut_slice().sort_by(compare)
     }
 
-    /// Returns a slice of `self` between `start` and `end`.
+    /// Returns a slice of self spanning the interval [`start`, `end`).
     ///
     /// # Failure
     ///
-    /// Fails when `start` or `end` point outside the bounds of `self`, or when
+    /// Fails when the slice (or part of it) is outside the bounds of self, or when
     /// `start` > `end`.
     ///
     /// # Example

src/libcore/slice.rs

@@ -366,9 +366,9 @@ impl<T> Container for ~[T] {
 /// Extension methods for vectors
 pub trait ImmutableVector<'a, T> {
     /**
-     * Returns a slice of self between `start` and `end`.
+     * Returns a slice of self spanning the interval [`start`, `end`).
      *
-     * Fails when `start` or `end` point outside the bounds of self,
+     * Fails when the slice (or part of it) is outside the bounds of self,
      * or when `start` > `end`.
      */
     fn slice(&self, start: uint, end: uint) -> &'a [T];

src/libnum/bigint.rs

@@ -653,6 +653,8 @@ impl FromStrRadix for BigUint {
 
 impl BigUint {
     /// Creates and initializes a `BigUint`.
+    ///
+    /// The digits are be in base 2^32.
     #[inline]
     pub fn new(v: Vec<BigDigit>) -> BigUint {
         // omit trailing zeros
@@ -665,6 +667,8 @@ impl BigUint {
     }
 
     /// Creates and initializes a `BigUint`.
+    ///
+    /// The digits are be in base 2^32.
     #[inline]
     pub fn from_slice(slice: &[BigDigit]) -> BigUint {
         return BigUint::new(Vec::from_slice(slice));
@@ -1315,12 +1319,16 @@ impl<R: Rng> RandBigInt for R {
 
 impl BigInt {
     /// Creates and initializes a BigInt.
+    ///
+    /// The digits are be in base 2^32.
     #[inline]
     pub fn new(sign: Sign, v: Vec<BigDigit>) -> BigInt {
         BigInt::from_biguint(sign, BigUint::new(v))
     }
 
     /// Creates and initializes a `BigInt`.
+    ///
+    /// The digits are be in base 2^32.
     #[inline]
     pub fn from_biguint(sign: Sign, data: BigUint) -> BigInt {
         if sign == Zero || data.is_zero() {