auto merge of #18880 : barosl/rust/doc-fail-to-panic, r=alexcrichton

I found some occurrences of "failure" and "fails" in the documentation. I changed them to "panics" if it means a task panic. Otherwise I left it as is, or changed it to "errors" to clearly distinguish them.

Also, I made a minor fix that is breaking the layout of a module page. "Example" is shown in an irrelevant place from the following page: http://doc.rust-lang.org/std/os/index.html

Author: bors

src/libcollections/bit.rs

@@ -258,9 +258,9 @@ impl Bitv {
 
     /// Retrieves the value at index `i`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `i` is out of bounds.
+    /// Panics if `i` is out of bounds.
     ///
     /// # Example
     ///
@@ -285,9 +285,9 @@ impl Bitv {
 
     /// Sets the value of a bit at a index `i`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `i` is out of bounds.
+    /// Panics if `i` is out of bounds.
     ///
     /// # Example
     ///
@@ -353,9 +353,9 @@ impl Bitv {
     /// Sets `self` to the union of `self` and `other`. Both bitvectors must be
     /// the same length. Returns `true` if `self` changed.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the bitvectors are of different lengths.
+    /// Panics if the bitvectors are of different lengths.
     ///
     /// # Example
     ///
@@ -383,9 +383,9 @@ impl Bitv {
     /// Sets `self` to the intersection of `self` and `other`. Both bitvectors
     /// must be the same length. Returns `true` if `self` changed.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the bitvectors are of different lengths.
+    /// Panics if the bitvectors are of different lengths.
     ///
     /// # Example
     ///
@@ -413,9 +413,9 @@ impl Bitv {
     /// element of `other` at the same index. Both bitvectors must be the same
     /// length. Returns `true` if `self` changed.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the bitvectors are of different length.
+    /// Panics if the bitvectors are of different length.
     ///
     /// # Example
     ///
@@ -580,9 +580,9 @@ impl Bitv {
     /// Compares a `Bitv` to a slice of `bool`s.
     /// Both the `Bitv` and slice must have the same length.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the the `Bitv` and slice are of different length.
+    /// Panics if the the `Bitv` and slice are of different length.
     ///
     /// # Example
     ///
@@ -718,7 +718,7 @@ impl Bitv {
 
     /// Shortens by one element and returns the removed element.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// Assert if empty.
     ///

src/libcollections/string.rs

@@ -498,9 +498,9 @@ impl String {
 
     /// Shortens a string to the specified length.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `new_len` > current length,
+    /// Panics if `new_len` > current length,
     /// or if `new_len` is not a character boundary.
     ///
     /// # Example

src/libcollections/vec.rs

@@ -941,9 +941,9 @@ impl<T> Vec<T> {
 
     /// Appends an element to the back of a collection.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the number of elements in the vector overflows a `uint`.
+    /// Panics if the number of elements in the vector overflows a `uint`.
     ///
     /// # Example
     ///
@@ -1462,9 +1462,9 @@ impl<T> Vec<T> {
     /// Converts a `Vec<T>` to a `Vec<U>` where `T` and `U` have the same
     /// size and in case they are not zero-sized the same minimal alignment.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `T` and `U` have differing sizes or are not zero-sized and
+    /// Panics if `T` and `U` have differing sizes or are not zero-sized and
     /// have differing minimal alignments.
     ///
     /// # Example

src/libcore/atomic.rs

@@ -102,19 +102,19 @@ impl AtomicBool {
 
     /// Load the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Release` or `AcqRel`.
+    /// Panics if `order` is `Release` or `AcqRel`.
     #[inline]
     pub fn load(&self, order: Ordering) -> bool {
         unsafe { atomic_load(self.v.get() as *const uint, order) > 0 }
     }
 
     /// Store the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is `Acquire` or `AcqRel`.
     #[inline]
     pub fn store(&self, val: bool, order: Ordering) {
         let val = if val { UINT_TRUE } else { 0 };
@@ -313,19 +313,19 @@ impl AtomicInt {
 
     /// Load the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Release` or `AcqRel`.
+    /// Panics if `order` is `Release` or `AcqRel`.
     #[inline]
     pub fn load(&self, order: Ordering) -> int {
         unsafe { atomic_load(self.v.get() as *const int, order) }
     }
 
     /// Store the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is `Acquire` or `AcqRel`.
     #[inline]
     pub fn store(&self, val: int, order: Ordering) {
         unsafe { atomic_store(self.v.get(), val, order); }
@@ -435,19 +435,19 @@ impl AtomicUint {
 
     /// Load the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Release` or `AcqRel`.
+    /// Panics if `order` is `Release` or `AcqRel`.
     #[inline]
     pub fn load(&self, order: Ordering) -> uint {
         unsafe { atomic_load(self.v.get() as *const uint, order) }
     }
 
     /// Store the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is `Acquire` or `AcqRel`.
     #[inline]
     pub fn store(&self, val: uint, order: Ordering) {
         unsafe { atomic_store(self.v.get(), val, order); }
@@ -557,9 +557,9 @@ impl<T> AtomicPtr<T> {
 
     /// Load the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Release` or `AcqRel`.
+    /// Panics if `order` is `Release` or `AcqRel`.
     #[inline]
     pub fn load(&self, order: Ordering) -> *mut T {
         unsafe {
@@ -569,9 +569,9 @@ impl<T> AtomicPtr<T> {
 
     /// Store the value
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `order` is `Acquire` or `AcqRel`.
+    /// Panics if `order` is `Acquire` or `AcqRel`.
     #[inline]
     pub fn store(&self, ptr: *mut T, order: Ordering) {
         unsafe { atomic_store(self.p.get(), ptr as uint, order); }
@@ -729,9 +729,9 @@ unsafe fn atomic_xor<T>(dst: *mut T, val: T, order: Ordering) -> T {
 ///
 /// Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if `order` is `Relaxed`
+/// Panics if `order` is `Relaxed`
 #[inline]
 #[stable]
 pub fn fence(order: Ordering) {

src/libcore/cell.rs

@@ -274,9 +274,9 @@ impl<T> RefCell<T> {
     /// The borrow lasts until the returned `Ref` exits scope. Multiple
     /// immutable borrows can be taken out at the same time.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the value is currently mutably borrowed.
+    /// Panics if the value is currently mutably borrowed.
     #[unstable]
     pub fn borrow<'a>(&'a self) -> Ref<'a, T> {
         match self.try_borrow() {
@@ -307,9 +307,9 @@ impl<T> RefCell<T> {
     /// The borrow lasts until the returned `RefMut` exits scope. The value
     /// cannot be borrowed while this borrow is active.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the value is currently borrowed.
+    /// Panics if the value is currently borrowed.
     #[unstable]
     pub fn borrow_mut<'a>(&'a self) -> RefMut<'a, T> {
         match self.try_borrow_mut() {

src/libcore/char.rs

@@ -87,9 +87,9 @@ pub fn from_u32(i: u32) -> Option<char> {
 /// Returns `true` if `c` is a valid digit under `radix`, and `false`
 /// otherwise.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if given a `radix` > 36.
+/// Panics if given a `radix` > 36.
 ///
 /// # Note
 ///
@@ -113,9 +113,9 @@ pub fn is_digit_radix(c: char, radix: uint) -> bool {
 /// 'b' or 'B', 11, etc. Returns none if the `char` does not
 /// refer to a digit in the given radix.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if given a `radix` outside the range `[0..36]`.
+/// Panics if given a `radix` outside the range `[0..36]`.
 ///
 #[inline]
 pub fn to_digit(c: char, radix: uint) -> Option<uint> {
@@ -140,9 +140,9 @@ pub fn to_digit(c: char, radix: uint) -> Option<uint> {
 /// Returns `Some(char)` if `num` represents one digit under `radix`,
 /// using one character of `0-9` or `a-z`, or `None` if it doesn't.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if given an `radix` > 36.
+/// Panics if given an `radix` > 36.
 ///
 #[inline]
 pub fn from_digit(num: uint, radix: uint) -> Option<char> {
@@ -240,9 +240,9 @@ pub trait Char {
     /// Returns `true` if `c` is a valid digit under `radix`, and `false`
     /// otherwise.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if given a radix > 36.
+    /// Panics if given a radix > 36.
     fn is_digit_radix(&self, radix: uint) -> bool;
 
     /// Converts a character to the corresponding digit.
@@ -253,9 +253,9 @@ pub trait Char {
     /// 9. If `c` is 'a' or 'A', 10. If `c` is 'b' or 'B', 11, etc. Returns
     /// none if the character does not refer to a digit in the given radix.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if given a radix outside the range [0..36].
+    /// Panics if given a radix outside the range [0..36].
     fn to_digit(&self, radix: uint) -> Option<uint>;
 
     /// Converts a number to the character representing it.
@@ -265,9 +265,9 @@ pub trait Char {
     /// Returns `Some(char)` if `num` represents one digit under `radix`,
     /// using one character of `0-9` or `a-z`, or `None` if it doesn't.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if given a radix > 36.
+    /// Panics if given a radix > 36.
     fn from_digit(num: uint, radix: uint) -> Option<Self>;
 
     /// Returns the hexadecimal Unicode escape of a character.

src/libcore/fmt/float.rs

@@ -72,11 +72,11 @@ static DIGIT_E_RADIX: uint = ('e' as uint) - ('a' as uint) + 11u;
  * - `f`             - A closure to invoke with the bytes representing the
  *                     float.
  *
- * # Failure
- * - Fails if `radix` < 2 or `radix` > 36.
- * - Fails if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
+ * # Panics
+ * - Panics if `radix` < 2 or `radix` > 36.
+ * - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
  *   between digit and exponent sign `'e'`.
- * - Fails if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
+ * - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
  *   between digit and exponent sign `'p'`.
  */
 pub fn float_to_str_bytes_common<T: Float, U>(