Updated comments in auto trait machinery.

Author: ibabushkin

src/librustc/traits/auto_trait.rs

@@ -68,9 +68,24 @@ impl<'a, 'tcx> AutoTraitFinder<'a, 'tcx> {
         AutoTraitFinder { tcx }
     }
 
-    /// Determine whether an auto trait is implemented for a type, and if this is the case if
-    /// non-trivial bounds need to be fulfilled, invoke a callback to compute a value representing
-    /// these in a fashion suitable for the caller.
+    /// Make a best effort to determine whether and under which conditions an auto trait is
+    /// implemented for a type. For example, if you have
+    ///
+    /// ```
+    /// struct Foo<T> { data: Box<T> }
+    /// ```
+
+    /// then this might return that Foo<T>: Send if T: Send (encoded in the AutoTraitResult type).
+    /// The analysis attempts to account for custom impls as well as other complex cases. This
+    /// result is intended for use by rustdoc and other such consumers.
+
+    /// (Note that due to the coinductive nature of Send, the full and correct result is actually
+    /// quite simple to generate. That is, when a type has no custom impl, it is Send iff its field
+    /// types are all Send. So, in our example, we might have that Foo<T>: Send if Box<T>: Send.
+    /// But this is often not the best way to present to the user.)
+
+    /// Warning: The API should be considered highly unstable, and it may be refactored or removed
+    /// in the future.
     pub fn find_auto_trait_generics<A>(
         &self,
         did: DefId,