auto merge of #11002 : pnkfelix/rust/fsk-improve-doc-for-ptr-offset, …

…r=alexcrichton

Spell out the units used for the `offset` argument, so that people do not try to scale to units of bytes themselves.

src/libstd/ptr.rs

@@ -21,14 +21,18 @@ use util::swap;
 
 #[cfg(not(test))] use cmp::{Eq, Ord};
 
-/// Calculate the offset from a pointer
+/// Calculate the offset from a pointer.
+/// The `count` argument is in units of T; e.g. a `count` of 3
+/// represents a pointer offset of `3 * sizeof::<T>()` bytes.
 #[inline]
 pub unsafe fn offset<T>(ptr: *T, count: int) -> *T {
     intrinsics::offset(ptr, count)
 }
 
 /// Calculate the offset from a mut pointer. The count *must* be in bounds or
 /// otherwise the loads of this address are undefined.
+/// The `count` argument is in units of T; e.g. a `count` of 3
+/// represents a pointer offset of `3 * sizeof::<T>()` bytes.
 #[inline]
 pub unsafe fn mut_offset<T>(ptr: *mut T, count: int) -> *mut T {
     intrinsics::offset(ptr as *T, count) as *mut T