diff --git a/src/libstd/num/int_macros.rs b/src/libstd/num/int_macros.rs
index a6b0ccf3a8725..cacd8d0aef91a 100644
--- a/src/libstd/num/int_macros.rs
+++ b/src/libstd/num/int_macros.rs
@@ -235,6 +235,16 @@ impl Primitive for $T {}
 // String conversion functions and impl str -> num
 
 /// Parse a byte slice as a number in the given base.
+///
+/// Yields an `Option` because `buf` may or may not actually be parseable.
+///
+/// # Examples
+///
+/// ```rust
+/// let digits = [49,50,51,52,53,54,55,56,57];
+/// let base   = 10;
+/// let num    = std::i64::parse_bytes(digits, base);
+/// ```
 #[inline]
 pub fn parse_bytes(buf: &[u8], radix: uint) -> Option<$T> {
     strconv::from_str_bytes_common(buf, radix, true, false, false,
diff --git a/src/libstd/num/uint_macros.rs b/src/libstd/num/uint_macros.rs
index 9b9aee672a0f5..697390a00699c 100644
--- a/src/libstd/num/uint_macros.rs
+++ b/src/libstd/num/uint_macros.rs
@@ -149,6 +149,16 @@ impl Int for $T {}
 // String conversion functions and impl str -> num
 
 /// Parse a byte slice as a number in the given base.
+///
+/// Yields an `Option` because `buf` may or may not actually be parseable.
+///
+/// # Examples
+///
+/// ```rust
+/// let digits = [49,50,51,52,53,54,55,56,57];
+/// let base   = 10;
+/// let num    = std::i64::parse_bytes(digits, base);
+/// ```
 #[inline]
 pub fn parse_bytes(buf: &[u8], radix: uint) -> Option<$T> {
     strconv::from_str_bytes_common(buf, radix, false, false, false,