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.

1 files changed, 5 insertions, 1 deletions

diff --git a/src/libstd/ptr.rs b/src/libstd/ptr.rs
index e2dda826765..162e46c53ae 100644
--- a/src/libstd/ptr.rs
+++ b/src/libstd/ptr.rs
@@ -21,7 +21,9 @@ 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)
@@ -29,6 +31,8 @@ pub unsafe fn offset<T>(ptr: *T, count: int) -> *T {
 
 /// 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