review suggestions

src/libcore/future/future.rs

@@ -68,13 +68,15 @@ pub trait Future {
     /// typically do *not* suffer the same problems of "all wakeups must poll
     /// all events"; they are more like `epoll(4)`.
     ///
-    /// An implementation of `poll` should strive to return quickly, and must
-    /// *never* block. Returning quickly prevents unnecessarily clogging up
+    /// An implementation of `poll` should strive to return quickly, and should
+    /// not block. Returning quickly prevents unnecessarily clogging up
     /// threads or event loops. If it is known ahead of time that a call to
     /// `poll` may end up taking awhile, the work should be offloaded to a
     /// thread pool (or something similar) to ensure that `poll` can return
     /// quickly.
     ///
+    /// An implementation of `poll` may also never cause memory unsafety.
+    ///
     /// # Panics
     ///
     /// Once a future has completed (returned `Ready` from `poll`),

src/libcore/task/wake.rs

@@ -29,6 +29,11 @@ pub struct RawWaker {
 ///
 /// The pointer passed to all functions inside the vtable is the `data` pointer
 /// from the enclosing [`RawWaker`] object.
+///
+/// The functions inside this struct are only intended be called on the `data`
+/// pointer of a properly constructed [`RawWaker`] object from inside the
+/// [`RawWaker`] implementation. Calling one of the contained functions using
+/// any other `data` pointer will cause undefined behavior.
 #[derive(PartialEq, Copy, Clone, Debug)]
 pub struct RawWakerVTable {
     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when