auto merge of #12420 : pnkfelix/rust/fsk-improve-doc-for-ptr-offset, r=alexcrichton

ptr::RawPtr, spell out units used for the `offset` argument.

spell out units used for the `offset` argument, so that callers do not
try to scale to byte units themselves.

(this was originally landed in PR #11002 for the stand-alone functions, but that PR did not modify the `RawPtr` methods, since that had no doc at all at the time.  Now `RawPtr` has the *only* documentation for `offset`, since the stand-alone functions went away in PR #12167 / PR #12248.)

Author: bors

src/libstd/ptr.rs

@@ -213,7 +213,8 @@ pub trait RawPtr<T> {
     /// be pointing to invalid memory.
     unsafe fn to_option(&self) -> Option<&T>;
     /// Calculates the offset from a pointer. The offset *must* be in-bounds of
-    /// the object, or one-byte-past-the-end.
+    /// the object, or one-byte-past-the-end.  `count` is in units of T; e.g. a
+    /// `count` of 3 represents a pointer offset of `3 * sizeof::<T>()` bytes.
     unsafe fn offset(self, count: int) -> Self;
 }