auto merge of #18773 : subhashb/rust/convert_remaining_failures_to_panic, r=steveklabnik

I have also renamed `fail` to `panic` in some non-documentation comments, where I thought it mattered.
Fixes #18677 

cc @steveklabnik

Author: bors

src/libcollections/slice.rs

@@ -424,7 +424,7 @@ fn merge_sort<T>(v: &mut [T], compare: |&T, &T| -> Ordering) {
     // allocate some memory to use as scratch memory, we keep the
     // length 0 so we can keep shallow copies of the contents of `v`
     // without risking the dtors running on an object twice if
-    // `compare` fails.
+    // `compare` panics.
     let mut working_space = Vec::with_capacity(2 * len);
     // these both are buffers of length `len`.
     let mut buf_dat = working_space.as_mut_ptr();

src/libcore/option.rs

@@ -303,7 +303,7 @@ impl<T> Option<T> {
     ///
     /// # Panics
     ///
-    /// Fails if the value is a `None` with a custom panic message provided by
+    /// Panics if the value is a `None` with a custom panic message provided by
     /// `msg`.
     ///
     /// # Example
@@ -315,7 +315,7 @@ impl<T> Option<T> {
     ///
     /// ```{.should_fail}
     /// let x: Option<&str> = None;
-    /// x.expect("the world is ending"); // fails with `world is ending`
+    /// x.expect("the world is ending"); // panics with `world is ending`
     /// ```
     #[inline]
     #[unstable = "waiting for conventions"]

src/libgetopts/lib.rs

@@ -569,7 +569,7 @@ impl fmt::Show for Fail_ {
 ///
 /// On success returns `Ok(Matches)`. Use methods such as `opt_present`
 /// `opt_str`, etc. to interrogate results.
-/// # Errors
+/// # Panics
 ///
 /// Returns `Err(Fail_)` on failure: use the `Show` implementation of `Fail_` to display
 /// information about it.
@@ -860,9 +860,9 @@ enum LengthLimit {
 /// Note: Function was moved here from `std::str` because this module is the only place that
 /// uses it, and because it was too specific for a general string function.
 ///
-/// #Failure:
+/// # Panics
 ///
-/// Fails during iteration if the string contains a non-whitespace
+/// Panics during iteration if the string contains a non-whitespace
 /// sequence longer than the limit.
 fn each_split_within<'a>(ss: &'a str, lim: uint, it: |&'a str| -> bool)
                      -> bool {

src/libgreen/stack.rs

@@ -42,7 +42,7 @@ impl Stack {
     pub fn new(size: uint) -> Stack {
         // Map in a stack. Eventually we might be able to handle stack
         // allocation failure, which would fail to spawn the task. But there's
-        // not many sensible things to do on OOM.  Failure seems fine (and is
+        // not many sensible things to do on OOM. Panic seems fine (and is
         // what the old stack allocation did).
         let stack = match MemoryMap::new(size, &[MapReadable, MapWritable,
                                                  MapNonStandardFlags(STACK_FLAGS)]) {

src/librand/distributions/exponential.rs

@@ -73,7 +73,7 @@ pub struct Exp {
 
 impl Exp {
     /// Construct a new `Exp` with the given shape parameter
-    /// `lambda`. Fails if `lambda <= 0`.
+    /// `lambda`. Panics if `lambda <= 0`.
     pub fn new(lambda: f64) -> Exp {
         assert!(lambda > 0.0, "Exp::new called with `lambda` <= 0");
         Exp { lambda_inverse: 1.0 / lambda }

src/librand/distributions/gamma.rs

@@ -95,7 +95,7 @@ impl Gamma {
     /// Construct an object representing the `Gamma(shape, scale)`
     /// distribution.
     ///
-    /// Fails if `shape <= 0` or `scale <= 0`.
+    /// Panics if `shape <= 0` or `scale <= 0`.
     pub fn new(shape: f64, scale: f64) -> Gamma {
         assert!(shape > 0.0, "Gamma::new called with shape <= 0");
         assert!(scale > 0.0, "Gamma::new called with scale <= 0");
@@ -208,7 +208,7 @@ enum ChiSquaredRepr {
 
 impl ChiSquared {
     /// Create a new chi-squared distribution with degrees-of-freedom
-    /// `k`. Fails if `k < 0`.
+    /// `k`. Panics if `k < 0`.
     pub fn new(k: f64) -> ChiSquared {
         let repr = if k == 1.0 {
             DoFExactlyOne
@@ -261,7 +261,7 @@ pub struct FisherF {
 
 impl FisherF {
     /// Create a new `FisherF` distribution, with the given
-    /// parameter. Fails if either `m` or `n` are not positive.
+    /// parameter. Panics if either `m` or `n` are not positive.
     pub fn new(m: f64, n: f64) -> FisherF {
         assert!(m > 0.0, "FisherF::new called with `m < 0`");
         assert!(n > 0.0, "FisherF::new called with `n < 0`");
@@ -302,7 +302,7 @@ pub struct StudentT {
 
 impl StudentT {
     /// Create a new Student t distribution with `n` degrees of
-    /// freedom. Fails if `n <= 0`.
+    /// freedom. Panics if `n <= 0`.
     pub fn new(n: f64) -> StudentT {
         assert!(n > 0.0, "StudentT::new called with `n <= 0`");
         StudentT {

src/librand/distributions/mod.rs

@@ -113,7 +113,7 @@ pub struct WeightedChoice<'a, T:'a> {
 impl<'a, T: Clone> WeightedChoice<'a, T> {
     /// Create a new `WeightedChoice`.
     ///
-    /// Fails if:
+    /// Panics if:
     /// - `v` is empty
     /// - the total weight is 0
     /// - the total weight is larger than a `uint` can contain.

src/librand/distributions/normal.rs

@@ -90,7 +90,11 @@ pub struct Normal {
 
 impl Normal {
     /// Construct a new `Normal` distribution with the given mean and
-    /// standard deviation. Fails if `std_dev < 0`.
+    /// standard deviation.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `std_dev < 0`.
     pub fn new(mean: f64, std_dev: f64) -> Normal {
         assert!(std_dev >= 0.0, "Normal::new called with `std_dev` < 0");
         Normal {
@@ -132,7 +136,11 @@ pub struct LogNormal {
 
 impl LogNormal {
     /// Construct a new `LogNormal` distribution with the given mean
-    /// and standard deviation. Fails if `std_dev < 0`.
+    /// and standard deviation.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `std_dev < 0`.
     pub fn new(mean: f64, std_dev: f64) -> LogNormal {
         assert!(std_dev >= 0.0, "LogNormal::new called with `std_dev` < 0");
         LogNormal { norm: Normal::new(mean, std_dev) }

src/librand/distributions/range.rs

@@ -55,7 +55,7 @@ pub struct Range<X> {
 
 impl<X: SampleRange + PartialOrd> Range<X> {
     /// Create a new `Range` instance that samples uniformly from
-    /// `[low, high)`. Fails if `low >= high`.
+    /// `[low, high)`. Panics if `low >= high`.
     pub fn new(low: X, high: X) -> Range<X> {
         assert!(low < high, "Range::new called with `low >= high`");
         SampleRange::construct_range(low, high)

src/librand/lib.rs

@@ -204,15 +204,18 @@ pub trait Rng {
         Generator { rng: self }
     }
 
-    /// Generate a random value in the range [`low`, `high`). Fails if
-    /// `low >= high`.
+    /// Generate a random value in the range [`low`, `high`).
     ///
     /// This is a convenience wrapper around
     /// `distributions::Range`. If this function will be called
     /// repeatedly with the same arguments, one should use `Range`, as
     /// that will amortize the computations that allow for perfect
     /// uniformity, as they only happen on initialization.
     ///
+    /// # Panics
+    ///
+    /// Panics if `low >= high`.
+    ///
     /// # Example
     ///
     /// ```rust

src/librbml/lib.rs

@@ -841,7 +841,7 @@ pub mod writer {
             // the encoded EBML (normally).  This is just for
             // efficiency.  When debugging, though, we can emit such
             // labels and then they will be checked by decoder to
-            // try and check failures more quickly.
+            // try and check panics more quickly.
             if DEBUG { self.wr_tagged_str(EsLabel as uint, label) }
             else { Ok(()) }
         }

src/libregex/compile.rs

@@ -66,7 +66,7 @@ pub enum Inst {
     Jump(InstIdx),
 
     // Jumps to the instruction at the first index given. If that leads to
-    // a failing state, then the instruction at the second index given is
+    // a panic state, then the instruction at the second index given is
     // tried.
     Split(InstIdx, InstIdx),
 }

src/librustc/middle/resolve.rs

@@ -766,7 +766,7 @@ impl NameBindings {
     }
 
     /**
-     * Returns the module node. Fails if this node does not have a module
+     * Returns the module node. Panics if this node does not have a module
      * definition.
      */
     fn get_module(&self) -> Rc<Module> {
@@ -1109,8 +1109,10 @@ impl<'a> Resolver<'a> {
      * corresponding to the innermost block ID and returns the name bindings
      * as well as the newly-created parent.
      *
-     * If this node does not have a module definition and we are not inside
-     * a block, fails.
+     * # Panics
+     *
+     * Panics if this node does not have a module definition and we are not inside
+     * a block.
      */
     fn add_child(&self,
                  name: Name,
@@ -2795,7 +2797,7 @@ impl<'a> Resolver<'a> {
         return Success(());
     }
 
-    // Resolves a glob import. Note that this function cannot fail; it either
+    // Resolves a glob import. Note that this function cannot panic; it either
     // succeeds or bails out (as importing * from an empty module or a module
     // that exports nothing is valid).
     fn resolve_glob_import(&mut self,

src/librustc/middle/ty.rs

@@ -3348,7 +3348,7 @@ pub fn lltype_is_sized<'tcx>(cx: &ctxt<'tcx>, ty: Ty<'tcx>) -> bool {
     }
 }
 
-// Return the smallest part of ty which is unsized. Fails if ty is sized.
+// Return the smallest part of `ty` which is unsized. Fails if `ty` is sized.
 // 'Smallest' here means component of the static representation of the type; not
 // the size of an object at runtime.
 pub fn unsized_part_of_type<'tcx>(cx: &ctxt<'tcx>, ty: Ty<'tcx>) -> Ty<'tcx> {
@@ -4916,7 +4916,7 @@ pub fn lookup_field_type<'tcx>(tcx: &ctxt<'tcx>,
 }
 
 // Look up the list of field names and IDs for a given struct.
-// Fails if the id is not bound to a struct.
+// Panics if the id is not bound to a struct.
 pub fn lookup_struct_fields(cx: &ctxt, did: ast::DefId) -> Vec<field_ty> {
     if did.krate == ast::LOCAL_CRATE {
         let struct_fields = cx.struct_fields.borrow();

src/librustc/middle/typeck/check/mod.rs

@@ -2606,7 +2606,7 @@ fn try_index_step<'a, 'tcx>(fcx: &FnCtxt<'a, 'tcx>,
 }
 
 /// Given the head of a `for` expression, looks up the `next` method in the
-/// `Iterator` trait. Fails if the expression does not implement `next`.
+/// `Iterator` trait. Panics if the expression does not implement `next`.
 ///
 /// The return type of this function represents the concrete element type
 /// `A` in the type `Iterator<A>` that the method returns.

src/librustc_trans/driver/mod.rs

@@ -143,7 +143,7 @@ pub fn commit_date_str() -> Option<&'static str> {
 }
 
 /// Prints version information and returns None on success or an error
-/// message on failure.
+/// message on panic.
 pub fn version(binary: &str, matches: &getopts::Matches) -> Option<String> {
     let verbose = match matches.opt_str("version").as_ref().map(|s| s.as_slice()) {
         None => false,
@@ -425,7 +425,7 @@ pub fn list_metadata(sess: &Session, path: &Path,
     metadata::loader::list_file_metadata(sess.target.target.options.is_like_osx, path, out)
 }
 
-/// Run a procedure which will detect failures in the compiler and print nicer
+/// Run a procedure which will detect panics in the compiler and print nicer
 /// error messages rather than just failing the test.
 ///
 /// The diagnostic emitter yielded to the procedure should be used for reporting
@@ -492,7 +492,7 @@ pub fn monitor(f: proc():Send) {
             }
 
             // Panic so the process returns a failure code, but don't pollute the
-            // output with some unnecessary failure messages, we've already
+            // output with some unnecessary panic messages, we've already
             // printed everything that we needed to.
             io::stdio::set_stderr(box io::util::NullWriter);
             panic!();

src/libstd/ascii.rs

@@ -216,7 +216,10 @@ pub trait OwnedAsciiCast {
     /// Check if convertible to ascii
     fn is_ascii(&self) -> bool;
 
-    /// Take ownership and cast to an ascii vector. Fail on non-ASCII input.
+    /// Take ownership and cast to an ascii vector.
+    /// # Panics
+    ///
+    /// Panic on non-ASCII input.
     #[inline]
     fn into_ascii(self) -> Vec<Ascii> {
         assert!(self.is_ascii());

src/libstd/c_vec.rs

@@ -64,7 +64,7 @@ impl<T> Drop for CVec<T> {
 impl<T> CVec<T> {
     /// Create a `CVec` from a raw pointer to a buffer with a given length.
     ///
-    /// Fails if the given pointer is null. The returned vector will not attempt
+    /// Panics if the given pointer is null. The returned vector will not attempt
     /// to deallocate the vector when dropped.
     ///
     /// # Arguments
@@ -83,7 +83,7 @@ impl<T> CVec<T> {
     /// Create a `CVec` from a foreign buffer, with a given length,
     /// and a function to run upon destruction.
     ///
-    /// Fails if the given pointer is null.
+    /// Panics if the given pointer is null.
     ///
     /// # Arguments
     ///

src/libstd/sys/windows/tty.rs

@@ -14,8 +14,8 @@
 //!
 //! This module contains the implementation of a Windows specific console TTY.
 //! Also converts between UTF-16 and UTF-8. Windows has very poor support for
-//! UTF-8 and some functions will fail. In particular ReadFile and ReadConsole
-//! will fail when the codepage is set to UTF-8 and a Unicode character is
+//! UTF-8 and some functions will panic. In particular ReadFile and ReadConsole
+//! will panic when the codepage is set to UTF-8 and a Unicode character is
 //! entered.
 //!
 //! FIXME
@@ -48,7 +48,7 @@ fn invalid_encoding() -> IoError {
 
 pub fn is_tty(fd: c_int) -> bool {
     let mut out: DWORD = 0;
-    // If this function doesn't fail then fd is a TTY
+    // If this function doesn't panic then fd is a TTY
     match unsafe { GetConsoleMode(get_osfhandle(fd) as HANDLE,
                                   &mut out as LPDWORD) } {
         0 => false,

src/libstd/time/duration.rs

@@ -65,7 +65,7 @@ pub const MAX: Duration = Duration {
 impl Duration {
     /// Makes a new `Duration` with given number of weeks.
     /// Equivalent to `Duration::seconds(weeks * 7 * 24 * 60 * 60), with overflow checks.
-    /// Fails when the duration is out of bounds.
+    /// Panics when the duration is out of bounds.
     #[inline]
     pub fn weeks(weeks: i64) -> Duration {
         let secs = weeks.checked_mul(SECS_PER_WEEK).expect("Duration::weeks out of bounds");
@@ -74,7 +74,7 @@ impl Duration {
 
     /// Makes a new `Duration` with given number of days.
     /// Equivalent to `Duration::seconds(days * 24 * 60 * 60)` with overflow checks.
-    /// Fails when the duration is out of bounds.
+    /// Panics when the duration is out of bounds.
     #[inline]
     pub fn days(days: i64) -> Duration {
         let secs = days.checked_mul(SECS_PER_DAY).expect("Duration::days out of bounds");
@@ -83,7 +83,7 @@ impl Duration {
 
     /// Makes a new `Duration` with given number of hours.
     /// Equivalent to `Duration::seconds(hours * 60 * 60)` with overflow checks.
-    /// Fails when the duration is out of bounds.
+    /// Panics when the duration is out of bounds.
     #[inline]
     pub fn hours(hours: i64) -> Duration {
         let secs = hours.checked_mul(SECS_PER_HOUR).expect("Duration::hours ouf of bounds");
@@ -92,15 +92,15 @@ impl Duration {
 
     /// Makes a new `Duration` with given number of minutes.
     /// Equivalent to `Duration::seconds(minutes * 60)` with overflow checks.
-    /// Fails when the duration is out of bounds.
+    /// Panics when the duration is out of bounds.
     #[inline]
     pub fn minutes(minutes: i64) -> Duration {
         let secs = minutes.checked_mul(SECS_PER_MINUTE).expect("Duration::minutes out of bounds");
         Duration::seconds(secs)
     }
 
     /// Makes a new `Duration` with given number of seconds.
-    /// Fails when the duration is more than `i64::MAX` milliseconds
+    /// Panics when the duration is more than `i64::MAX` milliseconds
     /// or less than `i64::MIN` milliseconds.
     #[inline]
     pub fn seconds(seconds: i64) -> Duration {