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

src/libcollections/bit.rs

@@ -258,9 +258,9 @@ pub fn with_capacity(nbits: uint, init: bool) -> 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 @@ pub fn get(&self, i: uint) -> bool {
 
     /// 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 @@ pub fn negate(&mut self) {
     /// 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 @@ pub fn union(&mut self, other: &Bitv) -> bool {
     /// 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 @@ pub fn intersect(&mut self, other: &Bitv) -> bool {
     /// 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 @@ pub fn to_bools(&self) -> Vec<bool> {
     /// 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 @@ pub fn grow(&mut self, n: uint, value: bool) {
 
     /// Shortens by one element and returns the removed element.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// Assert if empty.
     ///

src/libcollections/string.rs

@@ -498,9 +498,9 @@ pub fn as_bytes<'a>(&'a self) -> &'a [u8] {
 
     /// 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 @@ pub fn grow_fn(&mut self, n: uint, f: |uint| -> 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,9 +102,9 @@ pub fn new(v: bool) -> 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 }
@@ -112,9 +112,9 @@ pub fn load(&self, order: Ordering) -> bool {
 
     /// 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,9 +313,9 @@ pub fn new(v: int) -> 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) }
@@ -323,9 +323,9 @@ pub fn load(&self, order: Ordering) -> int {
 
     /// 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,9 +435,9 @@ pub fn new(v: uint) -> 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) }
@@ -445,9 +445,9 @@ pub fn load(&self, order: Ordering) -> uint {
 
     /// 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 @@ pub fn new(p: *mut 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 @@ pub fn load(&self, order: Ordering) -> *mut 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 @@ pub fn try_borrow<'a>(&'a self) -> Option<Ref<'a, 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 @@ pub fn try_borrow_mut<'a>(&'a self) -> Option<RefMut<'a, 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 @@ pub enum SignFormat {
  * - `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>(

src/libcore/slice.rs

@@ -62,7 +62,7 @@
 pub trait SlicePrelude<T> for Sized? {
     /// Returns a subslice spanning the interval [`start`, `end`).
     ///
-    /// Fails when the end of the new slice lies beyond the end of the
+    /// Panics when the end of the new slice lies beyond the end of the
     /// original slice (i.e. when `end > self.len()`) or when `start > end`.
     ///
     /// Slicing with `start` equal to `end` yields an empty slice.
@@ -71,7 +71,7 @@ pub trait SlicePrelude<T> for Sized? {
 
     /// Returns a subslice from `start` to the end of the slice.
     ///
-    /// Fails when `start` is strictly greater than the length of the original slice.
+    /// Panics when `start` is strictly greater than the length of the original slice.
     ///
     /// Slicing from `self.len()` yields an empty slice.
     #[unstable = "waiting on final error conventions/slicing syntax"]
@@ -79,7 +79,7 @@ pub trait SlicePrelude<T> for Sized? {
 
     /// Returns a subslice from the start of the slice to `end`.
     ///
-    /// Fails when `end` is strictly greater than the length of the original slice.
+    /// Panics when `end` is strictly greater than the length of the original slice.
     ///
     /// Slicing to `0` yields an empty slice.
     #[unstable = "waiting on final error conventions/slicing syntax"]
@@ -91,7 +91,7 @@ pub trait SlicePrelude<T> for Sized? {
     /// the index `mid` itself) and the second will contain all
     /// indices from `[mid, len)` (excluding the index `len` itself).
     ///
-    /// Fails if `mid > len`.
+    /// Panics if `mid > len`.
     #[unstable = "waiting on final error conventions"]
     fn split_at<'a>(&'a self, mid: uint) -> (&'a [T], &'a [T]);
 
@@ -121,9 +121,9 @@ pub trait SlicePrelude<T> for Sized? {
     /// `size`. The windows overlap. If the slice is shorter than
     /// `size`, the iterator returns no values.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `size` is 0.
+    /// Panics if `size` is 0.
     ///
     /// # Example
     ///
@@ -144,9 +144,9 @@ pub trait SlicePrelude<T> for Sized? {
     /// length of the slice, then the last chunk will not have length
     /// `size`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `size` is 0.
+    /// Panics if `size` is 0.
     ///
     /// # Example
     ///
@@ -267,7 +267,7 @@ fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Returns a mutable subslice spanning the interval [`start`, `end`).
     ///
-    /// Fails when the end of the new slice lies beyond the end of the
+    /// Panics when the end of the new slice lies beyond the end of the
     /// original slice (i.e. when `end > self.len()`) or when `start > end`.
     ///
     /// Slicing with `start` equal to `end` yields an empty slice.
@@ -276,7 +276,7 @@ fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Returns a mutable subslice from `start` to the end of the slice.
     ///
-    /// Fails when `start` is strictly greater than the length of the original slice.
+    /// Panics when `start` is strictly greater than the length of the original slice.
     ///
     /// Slicing from `self.len()` yields an empty slice.
     #[unstable = "waiting on final error conventions"]
@@ -284,7 +284,7 @@ fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Returns a mutable subslice from the start of the slice to `end`.
     ///
-    /// Fails when `end` is strictly greater than the length of the original slice.
+    /// Panics when `end` is strictly greater than the length of the original slice.
     ///
     /// Slicing to `0` yields an empty slice.
     #[unstable = "waiting on final error conventions"]
@@ -333,15 +333,15 @@ fn is_empty(&self) -> bool { self.len() == 0 }
     /// not divide the length of the slice, then the last chunk will not
     /// have length `chunk_size`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if `chunk_size` is 0.
+    /// Panics if `chunk_size` is 0.
     #[unstable = "waiting on iterator type name conventions"]
     fn chunks_mut<'a>(&'a mut self, chunk_size: uint) -> MutChunks<'a, T>;
 
     /// Swaps two elements in a slice.
     ///
-    /// Fails if `a` or `b` are out of bounds.
+    /// Panics if `a` or `b` are out of bounds.
     ///
     /// # Arguments
     ///
@@ -364,7 +364,7 @@ fn is_empty(&self) -> bool { self.len() == 0 }
     /// the index `mid` itself) and the second will contain all
     /// indices from `[mid, len)` (excluding the index `len` itself).
     ///
-    /// Fails if `mid > len`.
+    /// Panics if `mid > len`.
     ///
     /// # Example
     ///
@@ -1641,7 +1641,7 @@ fn set_memory(&mut self, value: u8) {
 
     /// Copies data from `src` to `dst`
     ///
-    /// `src` and `dst` must not overlap. Fails if the length of `dst`
+    /// `src` and `dst` must not overlap. Panics if the length of `dst`
     /// is less than the length of `src`.
     #[inline]
     pub fn copy_memory(dst: &mut [u8], src: &[u8]) {

src/libcore/str.rs

@@ -1084,7 +1084,7 @@ pub unsafe fn c_str_to_static_slice(s: *const i8) -> &'static str {
     ///
     /// Returns the substring from [`begin`..`end`).
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// If begin is greater than end.
     /// If end is greater than the length of the string.
@@ -1432,7 +1432,7 @@ pub trait StrPrelude for Sized? {
     ///
     /// This operation is `O(1)`.
     ///
-    /// Fails when `begin` and `end` do not point to valid characters
+    /// Panics when `begin` and `end` do not point to valid characters
     /// or point beyond the last character of the string.
     ///
     /// See also `slice_to` and `slice_from` for slicing prefixes and
@@ -1463,7 +1463,7 @@ pub trait StrPrelude for Sized? {
     ///
     /// Equivalent to `self.slice(begin, self.len())`.
     ///
-    /// Fails when `begin` does not point to a valid character, or is
+    /// Panics when `begin` does not point to a valid character, or is
     /// out of bounds.
     ///
     /// See also `slice`, `slice_to` and `slice_chars`.
@@ -1474,7 +1474,7 @@ pub trait StrPrelude for Sized? {
     ///
     /// Equivalent to `self.slice(0, end)`.
     ///
-    /// Fails when `end` does not point to a valid character, or is
+    /// Panics when `end` does not point to a valid character, or is
     /// out of bounds.
     ///
     /// See also `slice`, `slice_from` and `slice_chars`.
@@ -1493,7 +1493,7 @@ pub trait StrPrelude for Sized? {
     /// variants that use byte indices rather than code point
     /// indices.
     ///
-    /// Fails if `begin` > `end` or the either `begin` or `end` are
+    /// Panics if `begin` > `end` or the either `begin` or `end` are
     /// beyond the last character of the string.
     ///
     /// # Example
@@ -1577,7 +1577,7 @@ pub trait StrPrelude for Sized? {
     /// The start and end of the string (when `index == self.len()`)
     /// are considered to be boundaries.
     ///
-    /// Fails if `index` is greater than `self.len()`.
+    /// Panics if `index` is greater than `self.len()`.
     ///
     /// # Example
     ///
@@ -1645,7 +1645,7 @@ pub trait StrPrelude for Sized? {
     /// A record {ch: char, next: uint} containing the char value and the byte
     /// index of the next Unicode character.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// If `i` is greater than or equal to the length of the string.
     /// If `i` is not the index of the beginning of a valid UTF-8 character.
@@ -1657,7 +1657,7 @@ pub trait StrPrelude for Sized? {
     ///
     /// Returns 0 for next index if called on start index 0.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// If `i` is greater than the length of the string.
     /// If `i` is not an index following a valid UTF-8 character.
@@ -1674,7 +1674,7 @@ pub trait StrPrelude for Sized? {
     /// assert_eq!(s.char_at(4), 'c');
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// If `i` is greater than or equal to the length of the string.
     /// If `i` is not the index of the beginning of a valid UTF-8 character.
@@ -1682,7 +1682,7 @@ pub trait StrPrelude for Sized? {
 
     /// Plucks the character ending at the `i`th byte of a string.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// If `i` is greater than the length of the string.
     /// If `i` is not an index following a valid UTF-8 character.
@@ -1790,7 +1790,7 @@ pub trait StrPrelude for Sized? {
 
     /// Returns the byte offset of an inner slice relative to an enclosing outer slice.
     ///
-    /// Fails if `inner` is not a direct slice contained within self.
+    /// Panics if `inner` is not a direct slice contained within self.
     ///
     /// # Example
     ///

src/libgetopts/lib.rs

@@ -562,7 +562,7 @@ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 ///
 /// On success returns `Ok(Matches)`. Use methods such as `opt_present`
 /// `opt_str`, etc. to interrogate results.
-/// # Failure
+/// # Errors
 ///
 /// Returns `Err(Fail_)` on failure: use the `Show` implementation of `Fail_` to display
 /// information about it.

src/librustrt/c_str.rs

@@ -141,9 +141,9 @@ impl CString {
     /// API, so avoid calling it with a pointer to memory managed by Rust's
     /// allocator API, as the behaviour would not be well defined.
     ///
-    ///# Failure
+    ///# Panics
     ///
-    /// Fails if `buf` is null
+    /// Panics if `buf` is null
     pub unsafe fn new(buf: *const libc::c_char, owns_buffer: bool) -> CString {
         assert!(!buf.is_null());
         CString { buf: buf, owns_buffer_: owns_buffer }
@@ -291,9 +291,9 @@ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 pub trait ToCStr for Sized? {
     /// Copy the receiver into a CString.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the receiver has an interior null.
+    /// Panics the task if the receiver has an interior null.
     fn to_c_str(&self) -> CString;
 
     /// Unsafe variant of `to_c_str()` that doesn't check for nulls.
@@ -314,9 +314,9 @@ pub trait ToCStr for Sized? {
     /// }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the receiver has an interior null.
+    /// Panics the task if the receiver has an interior null.
     #[inline]
     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
         let c_str = self.to_c_str();

src/libstd/collections/hash/map.rs

@@ -1237,9 +1237,9 @@ pub fn find_copy(&self, k: &K) -> Option<V> {
 
     /// Return a copy of the value corresponding to the key.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the key is not present.
+    /// Panics if the key is not present.
     ///
     /// # Example
     ///

src/libstd/collections/hash/table.rs

@@ -489,9 +489,9 @@ pub fn shift(mut self) -> Option<GapThenFull<K, V, M>> {
 /// Rounds up to a multiple of a power of two. Returns the closest multiple
 /// of `target_alignment` that is higher or equal to `unrounded`.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if `target_alignment` is not a power of two.
+/// Panics if `target_alignment` is not a power of two.
 fn round_up_to_next(unrounded: uint, target_alignment: uint) -> uint {
     assert!(target_alignment.is_power_of_two());
     (unrounded + target_alignment - 1) & !(target_alignment - 1)

src/libstd/io/mod.rs

@@ -914,9 +914,9 @@ fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { (*self).read(buf) }
 /// Similar to `slice()` except this function only bounds the slice on the
 /// capacity of `v`, not the length.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails when `start` or `end` point outside the capacity of `v`, or when
+/// Panics when `start` or `end` point outside the capacity of `v`, or when
 /// `start` > `end`.
 // Private function here because we aren't sure if we want to expose this as
 // API yet. If so, it should be a method on Vec.

src/libstd/num/strconv.rs

@@ -88,8 +88,8 @@ pub enum SignFormat {
  * It returns a tuple because there can be ambiguity between a special value
  * and a number representation at higher bases.
  *
- * # Failure
- * - Fails if `radix` < 2 or `radix` > 36.
+ * # Panics
+ * - Panics if `radix` < 2 or `radix` > 36.
  */
 fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f: |u8|) {
     assert!(2 <= radix && radix <= 36);
@@ -172,11 +172,11 @@ fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f: |u8
  * It returns a tuple because there can be ambiguity between a special value
  * and a number representation at higher bases.
  *
- * # 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>(

src/libstd/os.rs

@@ -322,9 +322,9 @@ fn env_convert(input: Vec<Vec<u8>>) -> Vec<(Vec<u8>, Vec<u8>)> {
 /// Any invalid UTF-8 bytes in the value are replaced by \uFFFD. See
 /// `String::from_utf8_lossy()` for details.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if `n` has any interior NULs.
+/// Panics if `n` has any interior NULs.
 ///
 /// # Example
 ///
@@ -345,9 +345,9 @@ pub fn getenv(n: &str) -> Option<String> {
 /// Fetches the environment variable `n` byte vector from the current process,
 /// returning None if the variable isn't set.
 ///
-/// # Failure
+/// # Panics
 ///
-/// Fails if `n` has any interior NULs.
+/// Panics if `n` has any interior NULs.
 pub fn getenv_as_bytes(n: &str) -> Option<Vec<u8>> {
     use c_str::CString;
 
@@ -889,6 +889,7 @@ pub fn errno() -> uint {
 }
 
 /// Return the string corresponding to an `errno()` value of `errnum`.
+///
 /// # Example
 /// ```rust
 /// use std::os;
@@ -1474,7 +1475,7 @@ pub fn granularity() -> uint {
 
 #[cfg(windows)]
 impl Drop for MemoryMap {
-    /// Unmap the mapping. Fails the task if any of `VirtualFree`,
+    /// Unmap the mapping. Panics the task if any of `VirtualFree`,
     /// `UnmapViewOfFile`, or `CloseHandle` fail.
     fn drop(&mut self) {
         use libc::types::os::arch::extra::{LPCVOID, HANDLE};

src/libstd/path/mod.rs

@@ -154,9 +154,9 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the path contains a NUL.
+    /// Panics the task if the path contains a NUL.
     ///
     /// See individual Path impls for additional restrictions.
     #[inline]
@@ -443,9 +443,9 @@ fn extension_str<'a>(&'a self) -> Option<&'a str> {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the filename contains a NUL.
+    /// Panics the task if the filename contains a NUL.
     #[inline]
     fn set_filename<T: BytesContainer>(&mut self, filename: T) {
         assert!(!contains_nul(&filename));
@@ -469,9 +469,9 @@ fn set_filename<T: BytesContainer>(&mut self, filename: T) {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the extension contains a NUL.
+    /// Panics the task if the extension contains a NUL.
     fn set_extension<T: BytesContainer>(&mut self, extension: T) {
         assert!(!contains_nul(&extension));
 
@@ -518,9 +518,9 @@ fn set_extension<T: BytesContainer>(&mut self, extension: T) {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the filename contains a NUL.
+    /// Panics the task if the filename contains a NUL.
     #[inline]
     fn with_filename<T: BytesContainer>(&self, filename: T) -> Self {
         let mut p = self.clone();
@@ -543,9 +543,9 @@ fn with_filename<T: BytesContainer>(&self, filename: T) -> Self {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the extension contains a NUL.
+    /// Panics the task if the extension contains a NUL.
     #[inline]
     fn with_extension<T: BytesContainer>(&self, extension: T) -> Self {
         let mut p = self.clone();
@@ -602,9 +602,9 @@ fn dir_path(&self) -> Self {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the path contains a NUL.
+    /// Panics the task if the path contains a NUL.
     #[inline]
     fn push<T: BytesContainer>(&mut self, path: T) {
         assert!(!contains_nul(&path));
@@ -671,9 +671,9 @@ fn push_many<T: BytesContainer>(&mut self, paths: &[T]) {
     /// # }
     /// ```
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the path contains a NUL.
+    /// Panics the task if the path contains a NUL.
     #[inline]
     fn join<T: BytesContainer>(&self, path: T) -> Self {
         let mut p = self.clone();

src/libstd/path/posix.rs

@@ -327,9 +327,9 @@ fn ends_with_path(&self, child: &Path) -> bool {
 impl Path {
     /// Returns a new Path from a byte vector or string
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails the task if the vector contains a NUL.
+    /// Panics the task if the vector contains a NUL.
     #[inline]
     pub fn new<T: BytesContainer>(path: T) -> Path {
         GenericPath::new(path)

src/libstd/path/windows.rs

@@ -159,9 +159,9 @@ fn is_str(_: Option<&Path>) -> bool { true }
 impl GenericPathUnsafe for Path {
     /// See `GenericPathUnsafe::from_vec_unchecked`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if not valid UTF-8.
+    /// Panics if not valid UTF-8.
     #[inline]
     unsafe fn new_unchecked<T: BytesContainer>(path: T) -> Path {
         let (prefix, path) = Path::normalize_(path.container_as_str().unwrap());
@@ -173,9 +173,9 @@ unsafe fn new_unchecked<T: BytesContainer>(path: T) -> Path {
 
     /// See `GenericPathUnsafe::set_filename_unchecked`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if not valid UTF-8.
+    /// Panics if not valid UTF-8.
     unsafe fn set_filename_unchecked<T: BytesContainer>(&mut self, filename: T) {
         let filename = filename.container_as_str().unwrap();
         match self.sepidx_or_prefix_len() {
@@ -600,9 +600,9 @@ fn ends_with_path(&self, child: &Path) -> bool {
 impl Path {
     /// Returns a new `Path` from a `BytesContainer`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the vector contains a `NUL`, or if it contains invalid UTF-8.
+    /// Panics if the vector contains a `NUL`, or if it contains invalid UTF-8.
     ///
     /// # Example
     ///

src/libsync/comm/mod.rs

@@ -43,7 +43,7 @@
 //!    "rendezvous" channel where each sender atomically hands off a message to
 //!    a receiver.
 //!
-//! ## Failure Propagation
+//! ## Panic Propagation
 //!
 //! In addition to being a core primitive for communicating in rust, channels
 //! are the points at which panics are propagated among tasks.  Whenever the one

src/libsync/lock.rs

@@ -345,9 +345,9 @@ pub fn write<'a>(&'a self) -> RWLockWriteGuard<'a, T> {
     /// Access the underlying data immutably. May run concurrently with other
     /// reading tasks.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Failing will unlock the lock while unwinding. However, unlike all other
+    /// Panicking will unlock the lock while unwinding. However, unlike all other
     /// access modes, this will not poison the lock.
     pub fn read<'a>(&'a self) -> RWLockReadGuard<'a, T> {
         let guard = self.lock.read();

src/libtest/lib.rs

@@ -1116,7 +1116,7 @@ pub fn new() -> MetricMap {
 
     /// Load MetricDiff from a file.
     ///
-    /// # Failure
+    /// # Panics
     ///
     /// This function will panic if the path does not exist or the path does not
     /// contain a valid metric map.