diff --git a/github/doc.go b/github/doc.go
index e2066f1..a699bde 100644
--- a/github/doc.go
+++ b/github/doc.go
@@ -59,10 +59,10 @@ limited to 60 requests per hour, while authenticated clients can make up to
 that are not issued on behalf of a user, use the
 UnauthenticatedRateLimitedTransport.
 
-The Rate field on a client tracks the rate limit information based on the most
+The Rate method on a client returns the rate limit information based on the most
 recent API call.  This is updated on every call, but may be out of date if it's
 been some time since the last API call and other clients have made subsequent
-requests since then.  You can always call RateLimit() directly to get the most
+requests since then.  You can always call RateLimits() directly to get the most
 up-to-date rate limit data for the client.
 
 Learn more about GitHub rate limiting at
diff --git a/github/github.go b/github/github.go
index 8a64455..fb603d1 100644
--- a/github/github.go
+++ b/github/github.go
@@ -75,7 +75,7 @@ type Client struct {
 	UserAgent string
 
 	rateMu sync.Mutex
-	rate   Rate
+	rate   Rate // Rate limit for the client as determined by the most recent API call.
 
 	// Services used for talking to different parts of the GitHub API.
 	Activity      *ActivityService
@@ -487,7 +487,7 @@ func (r RateLimits) String() string {
 	return Stringify(r)
 }
 
-// RateLimit is deprecated.  Use RateLimits instead.
+// Deprecated: RateLimit is deprecated, use RateLimits instead.
 func (c *Client) RateLimit() (*Rate, *Response, error) {
 	limits, resp, err := c.RateLimits()
 	if limits == nil {