From 29f36362827dc97bf5710482242c71e6a73f005d Mon Sep 17 00:00:00 2001
From: Andrew Cann <shum@canndrew.org>
Date: Fri, 12 Aug 2016 01:22:34 +0800
Subject: [PATCH] Add explanations to tests

---
 src/test/compile-fail/call-fn-never-arg-wrong-type.rs | 2 ++
 src/test/compile-fail/never-assign-dead-code.rs       | 2 ++
 src/test/compile-fail/never-assign-wrong-type.rs      | 2 ++
 src/test/compile-fail/never-disabled.rs               | 2 ++
 src/test/compile-fail/never-fallback.rs               | 3 +++
 src/test/compile-fail/return-from-diverging.rs        | 2 ++
 src/test/compile-fail/return-unit-from-diverging.rs   | 3 +++
 src/test/run-fail/adjust_never.rs                     | 2 ++
 src/test/run-fail/call-fn-never-arg.rs                | 2 ++
 src/test/run-fail/cast-never.rs                       | 2 ++
 src/test/run-fail/never-associated-type.rs            | 2 ++
 src/test/run-fail/never-type-arg.rs                   | 2 ++
 src/test/run-fail/return-never-coerce.rs              | 2 ++
 src/test/run-pass/impl-for-never.rs                   | 2 ++
 src/test/run-pass/never-result.rs                     | 2 ++
 src/test/run-pass/never_coercions.rs                  | 3 +++
 src/test/run-pass/unit-fallback.rs                    | 2 ++
 17 files changed, 37 insertions(+)

diff --git a/src/test/compile-fail/call-fn-never-arg-wrong-type.rs b/src/test/compile-fail/call-fn-never-arg-wrong-type.rs
index cf340989ab73..583befed1e82 100644
--- a/src/test/compile-fail/call-fn-never-arg-wrong-type.rs
+++ b/src/test/compile-fail/call-fn-never-arg-wrong-type.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can't pass other types for !
+
 #![feature(never_type)]
 
 fn foo(x: !) -> ! {
diff --git a/src/test/compile-fail/never-assign-dead-code.rs b/src/test/compile-fail/never-assign-dead-code.rs
index 647ee74ac564..57e0bca6a6d7 100644
--- a/src/test/compile-fail/never-assign-dead-code.rs
+++ b/src/test/compile-fail/never-assign-dead-code.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that an assignment of type ! makes the rest of the block dead code.
+
 #![feature(never_type)]
 #![deny(unused, unreachable_code)]
 
diff --git a/src/test/compile-fail/never-assign-wrong-type.rs b/src/test/compile-fail/never-assign-wrong-type.rs
index 60184fd21b23..53d96aaf4fe8 100644
--- a/src/test/compile-fail/never-assign-wrong-type.rs
+++ b/src/test/compile-fail/never-assign-wrong-type.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can't use another type in place of !
+
 #![feature(never_type)]
 
 fn main() {
diff --git a/src/test/compile-fail/never-disabled.rs b/src/test/compile-fail/never-disabled.rs
index 00cb4f0b17a2..11b9f412957e 100644
--- a/src/test/compile-fail/never-disabled.rs
+++ b/src/test/compile-fail/never-disabled.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that ! errors when used in illegal positions with feature(never_type) disabled
+
 trait Foo {
     type Wub;
 }
diff --git a/src/test/compile-fail/never-fallback.rs b/src/test/compile-fail/never-fallback.rs
index 24547bd7c886..ca7b715547d2 100644
--- a/src/test/compile-fail/never-fallback.rs
+++ b/src/test/compile-fail/never-fallback.rs
@@ -8,6 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that diverging types default to ! when feature(never_type) is enabled. This test is the
+// same as run-pass/unit-fallback.rs except that ! is enabled.
+
 #![feature(never_type)]
 
 trait Balls: Sized {
diff --git a/src/test/compile-fail/return-from-diverging.rs b/src/test/compile-fail/return-from-diverging.rs
index 1221e1097014..cec59faa918b 100644
--- a/src/test/compile-fail/return-from-diverging.rs
+++ b/src/test/compile-fail/return-from-diverging.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that return another type in place of ! raises a type mismatch.
+
 fn fail() -> ! {
     return "wow"; //~ ERROR mismatched types
 }
diff --git a/src/test/compile-fail/return-unit-from-diverging.rs b/src/test/compile-fail/return-unit-from-diverging.rs
index 6b66c75582c4..ae2a325b24a9 100644
--- a/src/test/compile-fail/return-unit-from-diverging.rs
+++ b/src/test/compile-fail/return-unit-from-diverging.rs
@@ -8,6 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we get the usual error that we'd get for any other return type and not something about
+// diverging functions not being able to return.
+
 fn fail() -> ! {
     return; //~ ERROR in a function whose return type is not
 }
diff --git a/src/test/run-fail/adjust_never.rs b/src/test/run-fail/adjust_never.rs
index b390aae61434..ccdb1ca15bba 100644
--- a/src/test/run-fail/adjust_never.rs
+++ b/src/test/run-fail/adjust_never.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that a variable of type ! can coerce to another type.
+
 #![feature(never_type)]
 
 // error-pattern:explicit
diff --git a/src/test/run-fail/call-fn-never-arg.rs b/src/test/run-fail/call-fn-never-arg.rs
index b129f17a4378..95101e70db95 100644
--- a/src/test/run-fail/call-fn-never-arg.rs
+++ b/src/test/run-fail/call-fn-never-arg.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can use a ! for an argument of type !
+
 // error-pattern:wowzers!
 
 #![feature(never_type)]
diff --git a/src/test/run-fail/cast-never.rs b/src/test/run-fail/cast-never.rs
index 02ef0ad29b28..acd002494f4e 100644
--- a/src/test/run-fail/cast-never.rs
+++ b/src/test/run-fail/cast-never.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can explicitly cast ! to another type
+
 #![feature(never_type)]
 
 // error-pattern:explicit
diff --git a/src/test/run-fail/never-associated-type.rs b/src/test/run-fail/never-associated-type.rs
index 5fa2dfd3e887..345674f3f522 100644
--- a/src/test/run-fail/never-associated-type.rs
+++ b/src/test/run-fail/never-associated-type.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can use ! as an associated type.
+
 #![feature(never_type)]
 
 // error-pattern:kapow!
diff --git a/src/test/run-fail/never-type-arg.rs b/src/test/run-fail/never-type-arg.rs
index 7a563127f7f0..826ca3a08c0e 100644
--- a/src/test/run-fail/never-type-arg.rs
+++ b/src/test/run-fail/never-type-arg.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can use ! as an argument to a trait impl.
+
 // error-pattern:oh no!
 
 #![feature(never_type)]
diff --git a/src/test/run-fail/return-never-coerce.rs b/src/test/run-fail/return-never-coerce.rs
index 15e4834df881..4cd93ac7e1a5 100644
--- a/src/test/run-fail/return-never-coerce.rs
+++ b/src/test/run-fail/return-never-coerce.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that ! coerces to other types.
+
 // error-pattern:aah!
 
 fn call_another_fn<T, F: FnOnce() -> T>(f: F) -> T {
diff --git a/src/test/run-pass/impl-for-never.rs b/src/test/run-pass/impl-for-never.rs
index 504779ebeb50..4bb4e0128afa 100644
--- a/src/test/run-pass/impl-for-never.rs
+++ b/src/test/run-pass/impl-for-never.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can call static methods on ! both directly and when it appears in a generic
+
 #![feature(never_type)]
 
 trait StringifyType {
diff --git a/src/test/run-pass/never-result.rs b/src/test/run-pass/never-result.rs
index 555b059ee89e..5c0af392f44d 100644
--- a/src/test/run-pass/never-result.rs
+++ b/src/test/run-pass/never-result.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that we can extract a ! through pattern matching then use it as several different types.
+
 #![feature(never_type)]
 
 fn main() {
diff --git a/src/test/run-pass/never_coercions.rs b/src/test/run-pass/never_coercions.rs
index cee2a0a7d529..dfba5d2c3da0 100644
--- a/src/test/run-pass/never_coercions.rs
+++ b/src/test/run-pass/never_coercions.rs
@@ -8,6 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that having something of type ! doesn't screw up type-checking and that it coerces to the
+// LUB type of the other match arms.
+
 fn main() {
     let v: Vec<u32> = Vec::new();
     match 0u32 {
diff --git a/src/test/run-pass/unit-fallback.rs b/src/test/run-pass/unit-fallback.rs
index 6c3a80b78acb..c5c337dc0823 100644
--- a/src/test/run-pass/unit-fallback.rs
+++ b/src/test/run-pass/unit-fallback.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// Test that diverging types default to () (with feature(never_type) disabled).
+
 trait Balls: Sized {
     fn smeg() -> Result<Self, ()>;
 }