From 60184d12b6f90a520aef28316530f2cd1aeeded3 Mon Sep 17 00:00:00 2001
From: William Ting <william.h.ting@gmail.com>
Date: Mon, 21 Jan 2013 11:20:15 -0600
Subject: [PATCH] Update documentation with examples for various int, vec
 methods.

add int::range(), remainder() examples
add vec::foldl(), foldr() examples

tweak
---
 src/libcore/int-template.rs | 39 ++++++++++++++++++++++++++++++++++++-
 src/libcore/vec.rs          | 38 ++++++++++++++++++++++++++++++++++--
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/src/libcore/int-template.rs b/src/libcore/int-template.rs
index e62c7f095b0f..cc318fb4add1 100644
--- a/src/libcore/int-template.rs
+++ b/src/libcore/int-template.rs
@@ -45,6 +45,27 @@ pub pure fn sub(x: T, y: T) -> T { x - y }
 pub pure fn mul(x: T, y: T) -> T { x * y }
 #[inline(always)]
 pub pure fn div(x: T, y: T) -> T { x / y }
+
+/**
+ * Returns the remainder of y / x.
+ *
+ * # Examples
+ * ~~~
+ * assert int::rem(5 / 2) == 1;
+ * ~~~
+ *
+ * When faced with negative numbers, the result copies the sign of the
+ * dividend.
+ *
+ * ~~~
+ * assert int::rem(2 / -3) ==  2;
+ * ~~~
+ *
+ * ~~~
+ * assert int::rem(-2 / 3) ==  -2;
+ * ~~~
+ *
+ */
 #[inline(always)]
 pub pure fn rem(x: T, y: T) -> T { x % y }
 
@@ -70,8 +91,24 @@ pub pure fn is_nonpositive(x: T) -> bool { x <= 0 as T }
 #[inline(always)]
 pub pure fn is_nonnegative(x: T) -> bool { x >= 0 as T }
 
+/**
+ * Iterate over the range [`lo`..`hi`)
+ *
+ * # Arguments
+ *
+ * * `lo` - lower bound, inclusive
+ * * `hi` - higher bound, exclusive
+ *
+ * # Examples
+ * ~~~
+ * let mut sum = 0;
+ * for int::range(1, 5) |i| {
+ *     sum += i;
+ * }
+ * assert sum == 10;
+ * ~~~
+ */
 #[inline(always)]
-/// Iterate over the range [`lo`..`hi`)
 pub pure fn range(lo: T, hi: T, it: fn(T) -> bool) {
     let mut i = lo;
     while i < hi {
diff --git a/src/libcore/vec.rs b/src/libcore/vec.rs
index e6c2211b593f..763da29efcb5 100644
--- a/src/libcore/vec.rs
+++ b/src/libcore/vec.rs
@@ -922,7 +922,23 @@ pub pure fn connect<T: Copy>(v: &[~[T]], sep: &T) -> ~[T] {
     r
 }
 
-/// Reduce a vector from left to right
+/**
+ * Reduces a vector from left to right.
+ *
+ * # Arguments
+ * * `z` - initial accumulator value
+ * * `v` - vector to iterate over
+ * * `p` - a closure to do operate on vector elements
+ *
+ * # Examples
+ *
+ * Sum all values in the vector [1, 2, 3]:
+ *
+ * ~~~
+ * vec::foldl(0, [1, 2, 3], |a, b| a + *b);
+ * ~~~
+ *
+ */
 pub pure fn foldl<T, U>(z: T, v: &[U], p: fn(t: T, u: &U) -> T) -> T {
     let mut accum = z;
     let mut i = 0;
@@ -936,7 +952,25 @@ pub pure fn foldl<T, U>(z: T, v: &[U], p: fn(t: T, u: &U) -> T) -> T {
     return accum;
 }
 
-/// Reduce a vector from right to left
+/**
+ * Reduces a vector from right to left. Note that the argument order is
+ * reversed compared to `foldl` to reflect the order they are provided to
+ * the closure.
+ *
+ * # Arguments
+ * * `v` - vector to iterate over
+ * * `z` - initial accumulator value
+ * * `p` - a closure to do operate on vector elements
+ *
+ * # Examples
+ *
+ * Sum all values in the vector [1, 2, 3]:
+ *
+ * ~~~
+ * vec::foldr([1, 2, 3], 0, |a, b| a + *b);
+ * ~~~
+ *
+ */
 pub pure fn foldr<T, U: Copy>(v: &[T], z: U, p: fn(t: &T, u: U) -> U) -> U {
     let mut accum = z;
     for rev_each(v) |elt| {