improve comments

Author: nikomatsakis

src/test/incremental/change_add_field/struct_point.rs

@@ -69,7 +69,13 @@ mod point {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn that has the changed type in its signature; must currently be
+/// rebuilt.
+///
+/// You could imagine that, in the future, if the change were
+/// sufficiently "private", we might not need to type-check again.
+/// Rebuilding is probably always necessary since the layout may be
+/// affected.
 mod fn_with_type_in_sig {
     use point::Point;
 
@@ -79,6 +85,13 @@ mod fn_with_type_in_sig {
     }
 }
 
+/// Call a fn that has the changed type in its signature; this
+/// currently must also be rebuilt.
+///
+/// You could imagine that, in the future, if the change were
+/// sufficiently "private", we might not need to type-check again.
+/// Rebuilding is probably always necessary since the layout may be
+/// affected.
 mod call_fn_with_type_in_sig {
     use fn_with_type_in_sig;
 
@@ -88,7 +101,13 @@ mod call_fn_with_type_in_sig {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn that uses the changed type, but only in its body, not its
+/// signature.
+///
+/// You could imagine that, in the future, if the change were
+/// sufficiently "private", we might not need to type-check again.
+/// Rebuilding is probably always necessary since the layout may be
+/// affected.
 mod fn_with_type_in_body {
     use point::Point;
 
@@ -98,7 +117,10 @@ mod fn_with_type_in_body {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn X that calls a fn Y, where Y uses the changed type in its
+/// body. In this case, the effects of the change should be contained
+/// to Y; X should not have to be rebuilt, nor should it need to be
+/// typechecked again.
 mod call_fn_with_type_in_body {
     use fn_with_type_in_body;
 

src/test/incremental/change_pub_inherent_method_body/struct_point.rs

@@ -8,8 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// Test where we change the body of a private method in an impl.
-// We then test what sort of functions must be rebuilt as a result.
+// Test where we change the body of a public, inherent method.
 
 // revisions:rpass1 rpass2
 // compile-flags: -Z query-dep-graph
@@ -49,7 +48,7 @@ mod point {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn item that calls the method on `Point` which changed
 mod fn_calls_changed_method {
     use point::Point;
 
@@ -61,7 +60,7 @@ mod fn_calls_changed_method {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn item that calls a method on `Point` which did not change
 mod fn_calls_another_method {
     use point::Point;
 

src/test/incremental/change_pub_inherent_method_sig/struct_point.rs

@@ -8,8 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// Test where we change the body of a private method in an impl.
-// We then test what sort of functions must be rebuilt as a result.
+// Test where we change the *signature* of a public, inherent method.
 
 // revisions:rpass1 rpass2
 // compile-flags: -Z query-dep-graph
@@ -60,7 +59,7 @@ mod point {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn item that calls the method that was changed
 mod fn_calls_changed_method {
     use point::Point;
 
@@ -71,7 +70,7 @@ mod fn_calls_changed_method {
     }
 }
 
-/// A fn item that calls (public) methods on `Point` from the same impl which changed
+/// A fn item that calls a method that was not changed
 mod fn_calls_another_method {
     use point::Point;