Improve documentation of assume intrinsic.

Author: veddan

src/libcore/intrinsics.rs

@@ -259,7 +259,11 @@ extern "rust-intrinsic" {
     /// Inform the optimizer that a condition is always true.
     /// If the condition is false, the behavior is undefined.
     ///
-    /// No code is generated for this intrisic.
+    /// No code is generated for this intrinsic, but the optimizer will try
+    /// to preserve it (and its condition) between passes, which may interfere
+    /// with optimization of surrounding code and reduce performance. It should
+    /// not be used if the invariant can be discovered by the optimizer on its
+    /// own, or if it does not enable any significant optimizations.
     #[cfg(not(stage0))]
     pub fn assume(b: bool);