Flesh out the examples a bit more with surrounding context

RateLimiting.md

@@ -8,11 +8,24 @@ For higher rates, prefer a token bucket rate limiter such as [golang.org/x/time/
 ```go
 import "time"
 
-rate := time.Second / 10
+const rateLimit = time.Second / 10  // 10 calls per second
-throttle := time.Tick(rate)
+
-for req := range requests {
+// Client is an interface that calls something with a payload.
-  <-throttle  // rate limit our Service.Method RPCs
+type Client interface {
-  go client.Call("Service.Method", req, ...)
+  Call(*Payload)
+}
+
+// Payload is some payload a Client would send in a call.
+type Payload struct {}
+
+// RateLimitCall rate limits client calls with the payloads.
+func RateLimitCall(client Client, payloads []*Payload) {
+  throttle := time.Tick(rateLimit)
+
+  for _, payload := range payloads {
+    <-throttle  // rate limit our client calls
+    go client.Call(payload)
+  }
 }
 ```
 
@@ -20,21 +33,33 @@ To allow some bursts, add a buffer to the throttle:
 ```go
 import "time"
 
-rate := time.Second / 10
+const rateLimit = time.Second / 10  // 10 calls per second
-burstLimit := 100
+
-tick := time.NewTicker(rate)
+// Client is an interface that calls something with a payload.
-defer tick.Stop()
+type Client interface {
-throttle := make(chan time.Time, burstLimit)
+  Call(*Payload)
-go func() {
+}
-  for t := range tick.C {
+
-    select {
+// Payload is some payload a Client would send in a call.
-      case throttle <- t:
+type Payload struct {}
-      default:
+
-    }
+// BurstRateLimitCall allows burst rate limiting client calls with the
-  }  // does not exit after tick.Stop()
+// payloads.
-}()
+func BurstRateLimitCall(client Client, payloads []*Payload, burstLimit int) {
-for req := range requests {
+  ticker := time.NewTicker(rateLimit)
-  <-throttle  // rate limit our Service.Method RPCs
+  defer ticker.Stop()
-  go client.Call("Service.Method", req, ...)
+
+  throttle := make(chan time.Time, burstLimit)
+
+  go func() {
+    for t := range ticker.C {
+      throttle <- t
+    }  // for loop will complete the range after tick.Stop() closes tick.C
+  }()
+
+  for _, payload := range payloads {
+    <-throttle  // rate limit our client calls
+    go client.Call(payload)
+  }
 }
 ```