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

8 files changed, 40 insertions, 39 deletions

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 68c428f456d..4d26fa7e26c 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -1237,9 +1237,9 @@ impl<K: Eq + Hash<S>, V: Clone, S, H: Hasher<S>> HashMap<K, V, H> {
 
     /// 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
     ///
diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs
index 4838d3d73f1..05faba4950b 100644
--- a/src/libstd/collections/hash/table.rs
+++ b/src/libstd/collections/hash/table.rs
@@ -489,9 +489,9 @@ impl<K, V, M: Deref<RawTable<K, V>>> 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)
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 9828c2092d3..64fed1a5442 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -914,9 +914,9 @@ impl<'a> Reader for &'a mut Reader+'a {
 /// 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.
diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs
index 06d2f0ef028..fff31b332e1 100644
--- a/src/libstd/num/strconv.rs
+++ b/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>(
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index ea42117bab6..1402d3a3559 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -322,9 +322,9 @@ pub fn env_as_bytes() -> 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 @@ impl MemoryMap {
 
 #[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};
diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs
index e55933c4262..a185a29a700 100644
--- a/src/libstd/path/mod.rs
+++ b/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 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// # }
     /// ```
     ///
-    /// # 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 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// # }
     /// ```
     ///
-    /// # 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 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// # }
     /// ```
     ///
-    /// # 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 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// # }
     /// ```
     ///
-    /// # 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 @@ 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.
     #[inline]
     fn push<T: BytesContainer>(&mut self, path: T) {
         assert!(!contains_nul(&path));
@@ -671,9 +671,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.
     #[inline]
     fn join<T: BytesContainer>(&self, path: T) -> Self {
         let mut p = self.clone();
diff --git a/src/libstd/path/posix.rs b/src/libstd/path/posix.rs
index 9918e939097..794f6978642 100644
--- a/src/libstd/path/posix.rs
+++ b/src/libstd/path/posix.rs
@@ -327,9 +327,9 @@ impl GenericPath for Path {
 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)
diff --git a/src/libstd/path/windows.rs b/src/libstd/path/windows.rs
index 3a5350f0a29..2da2159653e 100644
--- a/src/libstd/path/windows.rs
+++ b/src/libstd/path/windows.rs
@@ -159,9 +159,9 @@ impl BytesContainer for Path {
 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 @@ impl GenericPathUnsafe for 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 @@ impl GenericPath for Path {
 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
     ///