return Response object from all API functions

The truth is, this change makes me sad.  It's a breaking change
for all clients and it adds more complexity to the library surface.  In
most cases, clients will simply drop the Response object on the floor
(which is actually all the library itself was doing before this
change... now we're just pushing that off to the client).

Initially, the Response object will be primarily of interest for
functions that return paginated result sets, since the Response.NextPage
field is the only way to know for sure if there are more pages that
should be fetched.  And this is really the cleanest way to get at that
data, so in that respect this change isn't so bad.

It's also worth noting that returning the raw Response object makes a
lot more since in a GitHub library than it may in others, given how
GitHub makes liberal (read: proper) use of HTTP request and response
headers.  Other APIs, like Google's various APIs for example, tend to
push things like pagination links into the response body.  While this is
certainly less of a purist view in terms of REST, it does make the lives
of client developers a lot easier, since then the response body contains
everything you need to know.  But whatever; this is how GitHub rolls, so
we'll roll right along with them.  (Somewhat ironically we are ignoring
the RESTful links in the GitHub response bodies, since we're actually
calling the API in an RPC style and don't do anything with those links.)

We still don't have an easy way to set arbitrary request headers, but
that's a problem for another day.

Fixes google#22

github/activity_events.go

@@ -62,7 +62,7 @@ type PushEventCommit struct {
 // true, only public events will be returned.
 //
 // GitHub API docs: http://developer.github.com/v3/activity/events/#list-events-performed-by-a-user
-func (s *ActivityService) ListEventsPerformedByUser(user string, publicOnly bool, opt *ListOptions) ([]Event, error) {
+func (s *ActivityService) ListEventsPerformedByUser(user string, publicOnly bool, opt *ListOptions) ([]Event, *Response, error) {
 	var u string
 	if publicOnly {
 		u = fmt.Sprintf("users/%v/events/public", user)
@@ -79,10 +79,10 @@ func (s *ActivityService) ListEventsPerformedByUser(user string, publicOnly bool
 
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	events := new([]Event)
-	_, err = s.client.Do(req, events)
-	return *events, err
+	resp, err := s.client.Do(req, events)
+	return *events, resp, err
 }

github/activity_events_test.go

@@ -26,7 +26,7 @@ func TestActivityService_ListEventsPerformedByUser_all(t *testing.T) {
 	})
 
 	opt := &ListOptions{Page: 2}
-	events, err := client.Activity.ListEventsPerformedByUser("u", false, opt)
+	events, _, err := client.Activity.ListEventsPerformedByUser("u", false, opt)
 	if err != nil {
 		t.Errorf("Events.ListPerformedByUser returned error: %v", err)
 	}
@@ -46,7 +46,7 @@ func TestActivityService_ListEventsPerformedByUser_publicOnly(t *testing.T) {
 		fmt.Fprint(w, `[{"id":"1"},{"id":"2"}]`)
 	})
 
-	events, err := client.Activity.ListEventsPerformedByUser("u", true, nil)
+	events, _, err := client.Activity.ListEventsPerformedByUser("u", true, nil)
 	if err != nil {
 		t.Errorf("Events.ListPerformedByUser returned error: %v", err)
 	}

github/activity_star.go

@@ -30,7 +30,7 @@ type ActivityListStarredOptions struct {
 // will list the starred repositories for the authenticated user.
 //
 // GitHub API docs: http://developer.github.com/v3/activity/starring/#list-repositories-being-starred
-func (s *ActivityService) ListStarred(user string, opt *ActivityListStarredOptions) ([]Repository, error) {
+func (s *ActivityService) ListStarred(user string, opt *ActivityListStarredOptions) ([]Repository, *Response, error) {
 	var u string
 	if user != "" {
 		u = fmt.Sprintf("users/%v/starred", user)
@@ -47,10 +47,10 @@ func (s *ActivityService) ListStarred(user string, opt *ActivityListStarredOptio
 	}
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	repos := new([]Repository)
-	_, err = s.client.Do(req, repos)
-	return *repos, err
+	resp, err := s.client.Do(req, repos)
+	return *repos, resp, err
 }

github/activity_star_test.go

@@ -21,7 +21,7 @@ func TestActivityService_ListStarred_authenticatedUser(t *testing.T) {
 		fmt.Fprint(w, `[{"id":1}]`)
 	})
 
-	repos, err := client.Activity.ListStarred("", nil)
+	repos, _, err := client.Activity.ListStarred("", nil)
 	if err != nil {
 		t.Errorf("Activity.ListStarred returned error: %v", err)
 	}
@@ -47,7 +47,7 @@ func TestActivityService_ListStarred_specifiedUser(t *testing.T) {
 	})
 
 	opt := &ActivityListStarredOptions{"created", "asc", 2}
-	repos, err := client.Activity.ListStarred("u", opt)
+	repos, _, err := client.Activity.ListStarred("u", opt)
 	if err != nil {
 		t.Errorf("Activity.ListStarred returned error: %v", err)
 	}

github/gists.go

@@ -57,7 +57,7 @@ type GistListOptions struct {
 // user.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#list-gists
-func (s *GistsService) List(user string, opt *GistListOptions) ([]Gist, error) {
+func (s *GistsService) List(user string, opt *GistListOptions) ([]Gist, *Response, error) {
 	var u string
 	if user != "" {
 		u = fmt.Sprintf("users/%v/gists", user)
@@ -74,18 +74,18 @@ func (s *GistsService) List(user string, opt *GistListOptions) ([]Gist, error) {
 
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	gists := new([]Gist)
-	_, err = s.client.Do(req, gists)
-	return *gists, err
+	resp, err := s.client.Do(req, gists)
+	return *gists, resp, err
 }
 
 // ListAll lists all public gists.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#list-gists
-func (s *GistsService) ListAll(opt *GistListOptions) ([]Gist, error) {
+func (s *GistsService) ListAll(opt *GistListOptions) ([]Gist, *Response, error) {
 	u := "gists/public"
 	if opt != nil {
 		params := url.Values{}
@@ -97,18 +97,18 @@ func (s *GistsService) ListAll(opt *GistListOptions) ([]Gist, error) {
 
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	gists := new([]Gist)
-	_, err = s.client.Do(req, gists)
-	return *gists, err
+	resp, err := s.client.Do(req, gists)
+	return *gists, resp, err
 }
 
 // ListStarred lists starred gists of authenticated user.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#list-gists
-func (s *GistsService) ListStarred(opt *GistListOptions) ([]Gist, error) {
+func (s *GistsService) ListStarred(opt *GistListOptions) ([]Gist, *Response, error) {
 	u := "gists/starred"
 	if opt != nil {
 		params := url.Values{}
@@ -120,118 +120,116 @@ func (s *GistsService) ListStarred(opt *GistListOptions) ([]Gist, error) {
 
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	gists := new([]Gist)
-	_, err = s.client.Do(req, gists)
-	return *gists, err
+	resp, err := s.client.Do(req, gists)
+	return *gists, resp, err
 }
 
 // Get a single gist.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#get-a-single-gist
-func (s *GistsService) Get(id string) (*Gist, error) {
+func (s *GistsService) Get(id string) (*Gist, *Response, error) {
 	u := fmt.Sprintf("gists/%v", id)
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	gist := new(Gist)
-	_, err = s.client.Do(req, gist)
-	return gist, err
+	resp, err := s.client.Do(req, gist)
+	return gist, resp, err
 }
 
 // Create a gist for authenticated user.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#create-a-gist
-func (s *GistsService) Create(gist *Gist) (*Gist, error) {
+func (s *GistsService) Create(gist *Gist) (*Gist, *Response, error) {
 	u := "gists"
 	req, err := s.client.NewRequest("POST", u, gist)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	g := new(Gist)
-	_, err = s.client.Do(req, g)
-	return g, err
+	resp, err := s.client.Do(req, g)
+	return g, resp, err
 }
 
 // Edit a gist.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#edit-a-gist
-func (s *GistsService) Edit(id string, gist *Gist) (*Gist, error) {
+func (s *GistsService) Edit(id string, gist *Gist) (*Gist, *Response, error) {
 	u := fmt.Sprintf("gists/%v", id)
 	req, err := s.client.NewRequest("PATCH", u, gist)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	g := new(Gist)
-	_, err = s.client.Do(req, g)
-	return g, err
+	resp, err := s.client.Do(req, g)
+	return g, resp, err
 }
 
 // Delete a gist.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#delete-a-gist
-func (s *GistsService) Delete(id string) error {
+func (s *GistsService) Delete(id string) (*Response, error) {
 	u := fmt.Sprintf("gists/%v", id)
 	req, err := s.client.NewRequest("DELETE", u, nil)
 	if err != nil {
-		return err
+		return nil, err
 	}
-	_, err = s.client.Do(req, nil)
-	return err
+	return s.client.Do(req, nil)
 }
 
 // Star a gist on behalf of authenticated user.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#star-a-gist
-func (s *GistsService) Star(id string) error {
+func (s *GistsService) Star(id string) (*Response, error) {
 	u := fmt.Sprintf("gists/%v/star", id)
 	req, err := s.client.NewRequest("PUT", u, nil)
 	if err != nil {
-		return err
+		return nil, err
 	}
-	_, err = s.client.Do(req, nil)
-	return err
+	return s.client.Do(req, nil)
 }
 
 // Unstar a gist on a behalf of authenticated user.
 //
 // Github API docs: http://developer.github.com/v3/gists/#unstar-a-gist
-func (s *GistsService) Unstar(id string) error {
+func (s *GistsService) Unstar(id string) (*Response, error) {
 	u := fmt.Sprintf("gists/%v/star", id)
 	req, err := s.client.NewRequest("DELETE", u, nil)
 	if err != nil {
-		return err
+		return nil, err
 	}
-	_, err = s.client.Do(req, nil)
-	return err
+	return s.client.Do(req, nil)
 }
 
 // Starred checks if a gist is starred by authenticated user.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#check-if-a-gist-is-starred
-func (s *GistsService) Starred(id string) (bool, error) {
+func (s *GistsService) Starred(id string) (bool, *Response, error) {
 	u := fmt.Sprintf("gists/%v/star", id)
 	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
-		return false, err
+		return false, nil, err
 	}
-	_, err = s.client.Do(req, nil)
-	return parseBoolResponse(err)
+	resp, err := s.client.Do(req, nil)
+	starred, err := parseBoolResponse(err)
+	return starred, resp, err
 }
 
 // Fork a gist.
 //
 // GitHub API docs: http://developer.github.com/v3/gists/#fork-a-gist
-func (s *GistsService) Fork(id string) (*Gist, error) {
+func (s *GistsService) Fork(id string) (*Gist, *Response, error) {
 	u := fmt.Sprintf("gists/%v/forks", id)
 	req, err := s.client.NewRequest("POST", u, nil)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	g := new(Gist)
-	_, err = s.client.Do(req, g)
-	return g, err
+	resp, err := s.client.Do(req, g)
+	return g, resp, err
 }