add/update docs (no substantive changes)

README.md

@@ -8,9 +8,13 @@ go-github is Go library for accessing the [GitHub API][].
 
 ## Usage ##
 
+```go
+import "github.com/google/go-github/github"
+```
+
 Construct a new GitHub client, then use the various services on the client to
-access different parts of the GitHub API.  For example, list all organizations
-for user "willnorris":
+access different parts of the GitHub API.  For example, to list all
+organizations for user "willnorris":
 
 ```go
 client := github.NewClient(nil)
@@ -18,7 +22,8 @@ orgs, err := client.Organizations.List("willnorris", nil)
 ```
 
 Some API methods have optional parameters that can be passed.  For example,
-list recently updated repositories for org "github":
+to list repositories for org "github", sorted by the time they were last
+updated:
 
 ```go
 client := github.NewClient(nil)
@@ -28,15 +33,15 @@ repos, err := client.Repositories.ListByOrg("github", opt)
 
 The go-github library does not directly handle authentication.  Instead, when
 creating a new client, pass an `http.Client` that can handle authentication for
-you.  The easiest, and recommended, way to do this is using the [goauth2][]
-library, but you can of course use any other library that provides an
-`http.Client`.  For example, to use the goauth2 library with an existing OAuth2
-access token:
+you.  The easiest and recommended way to do this is using the [goauth2][]
+library, but you can always use any other library that provides an
+`http.Client`.  If you have an OAuth2 access token (for example, a [personal
+API token][]), you can use it with the goauth2 library like so:
 
 ```go
 t := &oauth.Transport{
   Config: &oauth.Config{},
-  Token: &oauth.Token{AccessToken: "..."},
+  Token: &oauth.Token{AccessToken: "... your access token ..."},
 }
 
 client := github.NewClient(t.Client())
@@ -54,6 +59,7 @@ almost never be shared between different users.
 [GitHub API]: http://developer.github.com/v3/
 [goauth2]: https://code.google.com/p/goauth2/
 [goauth2 docs]: http://godoc.org/code.google.com/p/goauth2/oauth
+[personal API token]: https://github.com/blog/1509-personal-api-tokens
 
 
 ## Roadmap ##

github/github.go

@@ -90,7 +90,8 @@ type ListOptions struct {
 
 // NewClient returns a new GitHub API client.  If a nil httpClient is
 // provided, http.DefaultClient will be used.  To use API methods which require
-// authentication, provide an http.Client that can handle that.
+// authentication, provide an http.Client that will perform the authentication
+// for you (such as that provided by the goauth2 library).
 func NewClient(httpClient *http.Client) *Client {
 	if httpClient == nil {
 		httpClient = http.DefaultClient
@@ -200,9 +201,10 @@ func (e *Error) Error() string {
 }
 
 // CheckResponse checks the API response for errors, and returns them if
-// present.  API error responses are expected to have either no response body,
-// or a JSON response body that maps to ErrorResponse.  Any other response body
-// will be silently ignored.
+// present.  A response is considered an error if it has a status code outside
+// the 200 range.  API error responses are expected to have either no response
+// body, or a JSON response body that maps to ErrorResponse.  Any other
+// response body will be silently ignored.
 func CheckResponse(r *http.Response) error {
 	if c := r.StatusCode; 200 <= c && c <= 299 {
 		return nil

github/orgs.go

@@ -22,6 +22,7 @@ type OrganizationsService struct {
 	client *Client
 }
 
+// Organization represents a GitHub organization account.
 type Organization struct {
 	Login     string     `json:"login,omitempty"`
 	ID        int        `json:"id,omitempty"`
@@ -31,6 +32,8 @@ type Organization struct {
 	CreatedAt *time.Time `json:"created_at,omitempty"`
 }
 
+// Team represents a team within a GitHub organization.  Teams are used to
+// manage access to an organization's repositories.
 type Team struct {
 	ID           int    `json:"id,omitempty"`
 	Name         string `json:"name,omitempty"`
@@ -43,6 +46,8 @@ type Team struct {
 
 // List the organizations for a user.  Passing the empty string will list
 // organizations for the authenticated user.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/#list-user-organizations
 func (s *OrganizationsService) List(user string, opt *ListOptions) ([]Organization, error) {
 	var url_ string
 	if user != "" {
@@ -67,7 +72,9 @@ func (s *OrganizationsService) List(user string, opt *ListOptions) ([]Organizati
 	return *orgs, err
 }
 
-// Get an organization.
+// Get fetches an organization by name.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/#get-an-organization
 func (s *OrganizationsService) Get(org string) (*Organization, error) {
 	url_ := fmt.Sprintf("orgs/%v", org)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -81,6 +88,8 @@ func (s *OrganizationsService) Get(org string) (*Organization, error) {
 }
 
 // Edit an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/#edit-an-organization
 func (s *OrganizationsService) Edit(name string, org *Organization) (*Organization, error) {
 	url_ := fmt.Sprintf("orgs/%v", name)
 	req, err := s.client.NewRequest("PATCH", url_, org)
@@ -94,8 +103,10 @@ func (s *OrganizationsService) Edit(name string, org *Organization) (*Organizati
 }
 
 // List the members for an organization.  If the authenticated user is an owner
-// of the organization, this will return concealed and public members,
+// of the organization, this will return both concealed and public members,
 // otherwise it will only return public members.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#members-list
 func (s *OrganizationsService) ListMembers(org string) ([]User, error) {
 	url_ := fmt.Sprintf("orgs/%v/members", org)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -109,6 +120,8 @@ func (s *OrganizationsService) ListMembers(org string) ([]User, error) {
 }
 
 // List the public members for an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#public-members-list
 func (s *OrganizationsService) ListPublicMembers(org string) ([]User, error) {
 	url_ := fmt.Sprintf("orgs/%v/public_members", org)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -122,6 +135,8 @@ func (s *OrganizationsService) ListPublicMembers(org string) ([]User, error) {
 }
 
 // CheckMembership checks if a user is a member of an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#check-membership
 func (s *OrganizationsService) CheckMembership(org, user string) (bool, error) {
 	url_ := fmt.Sprintf("orgs/%v/members/%v", org, user)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -145,6 +160,8 @@ func (s *OrganizationsService) CheckMembership(org, user string) (bool, error) {
 }
 
 // CheckPublicMembership checks if a user is a public member of an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#check-public-membership
 func (s *OrganizationsService) CheckPublicMembership(org, user string) (bool, error) {
 	url_ := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -168,6 +185,8 @@ func (s *OrganizationsService) CheckPublicMembership(org, user string) (bool, er
 }
 
 // RemoveMember removes a user from all teams of an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#remove-a-member
 func (s *OrganizationsService) RemoveMember(org, user string) error {
 	url_ := fmt.Sprintf("orgs/%v/members/%v", org, user)
 	req, err := s.client.NewRequest("DELETE", url_, nil)
@@ -179,7 +198,9 @@ func (s *OrganizationsService) RemoveMember(org, user string) error {
 	return err
 }
 
-// Publicize a user's membership in an organization.
+// PublicizeMembership publicizes a user's membership in an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#publicize-a-users-membership
 func (s *OrganizationsService) PublicizeMembership(org, user string) error {
 	url_ := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
 	req, err := s.client.NewRequest("PUT", url_, nil)
@@ -191,7 +212,9 @@ func (s *OrganizationsService) PublicizeMembership(org, user string) error {
 	return err
 }
 
-// Conceal a user's membership in an organization.
+// ConcealMembership conceals a user's membership in an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/members/#conceal-a-users-membership
 func (s *OrganizationsService) ConcealMembership(org, user string) error {
 	url_ := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
 	req, err := s.client.NewRequest("DELETE", url_, nil)
@@ -203,7 +226,9 @@ func (s *OrganizationsService) ConcealMembership(org, user string) error {
 	return err
 }
 
-// List the teams for an organization.
+// ListTeams lists all of the teams for an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#list-teams
 func (s *OrganizationsService) ListTeams(org string) ([]Team, error) {
 	url_ := fmt.Sprintf("orgs/%v/teams", org)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -217,6 +242,8 @@ func (s *OrganizationsService) ListTeams(org string) ([]Team, error) {
 }
 
 // GetTeam fetches a team by ID.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#get-team
 func (s *OrganizationsService) GetTeam(team int) (*Team, error) {
 	url_ := fmt.Sprintf("teams/%v", team)
 	req, err := s.client.NewRequest("GET", url_, nil)
@@ -229,7 +256,9 @@ func (s *OrganizationsService) GetTeam(team int) (*Team, error) {
 	return t, err
 }
 
-// CreateTeam creates a new team.
+// CreateTeam creates a new team within an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#create-team
 func (s *OrganizationsService) CreateTeam(org string, team *Team) (*Team, error) {
 	url_ := fmt.Sprintf("orgs/%v/teams", org)
 	req, err := s.client.NewRequest("POST", url_, team)
@@ -243,6 +272,8 @@ func (s *OrganizationsService) CreateTeam(org string, team *Team) (*Team, error)
 }
 
 // EditTeam edits a team.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#edit-team
 func (s *OrganizationsService) EditTeam(id int, team *Team) (*Team, error) {
 	url_ := fmt.Sprintf("teams/%v", id)
 	req, err := s.client.NewRequest("PATCH", url_, team)
@@ -256,6 +287,8 @@ func (s *OrganizationsService) EditTeam(id int, team *Team) (*Team, error) {
 }
 
 // DeleteTeam deletes a team.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#delete-team
 func (s *OrganizationsService) DeleteTeam(team int) error {
 	url_ := fmt.Sprintf("teams/%v", team)
 	req, err := s.client.NewRequest("DELETE", url_, nil)
@@ -267,7 +300,9 @@ func (s *OrganizationsService) DeleteTeam(team int) error {
 	return err
 }
 
-// Add a user to a team.
+// AddTeamMember adds a user to a team.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#add-team-member
 func (s *OrganizationsService) AddTeamMember(team int, user string) error {
 	url_ := fmt.Sprintf("teams/%v/members/%v", team, user)
 	req, err := s.client.NewRequest("PUT", url_, nil)
@@ -279,7 +314,9 @@ func (s *OrganizationsService) AddTeamMember(team int, user string) error {
 	return err
 }
 
-// Remove a user from a team.
+// RemoveTeamMember removes a user from a team.
+//
+// GitHub API docs: http://developer.github.com/v3/orgs/teams/#remove-team-member
 func (s *OrganizationsService) RemoveTeamMember(team int, user string) error {
 	url_ := fmt.Sprintf("teams/%v/members/%v", team, user)
 	req, err := s.client.NewRequest("DELETE", url_, nil)

github/repos.go

@@ -21,6 +21,7 @@ type RepositoriesService struct {
 	client *Client
 }
 
+// Repository represents a GitHub repository.
 type Repository struct {
 	ID          int        `json:"id,omitempty"`
 	Owner       *User      `json:"owner,omitempty"`
@@ -52,6 +53,8 @@ type RepositoryListOptions struct {
 
 // List the repositories for a user.  Passing the empty string will list
 // repositories for the authenticated user.
+//
+// GitHub API docs: http://developer.github.com/v3/repos/#list-user-repositories
 func (s *RepositoriesService) List(user string, opt *RepositoryListOptions) ([]Repository, error) {
 	var url_ string
 	if user != "" {
@@ -90,7 +93,9 @@ type RepositoryListByOrgOptions struct {
 	Page int
 }
 
-// List the repositories for an organization.
+// ListByOrg lists the repositories for an organization.
+//
+// GitHub API docs: http://developer.github.com/v3/repos/#list-organization-repositories
 func (s *RepositoriesService) ListByOrg(org string, opt *RepositoryListByOrgOptions) ([]Repository, error) {
 	url_ := fmt.Sprintf("orgs/%v/repos", org)
 	if opt != nil {
@@ -112,6 +117,8 @@ func (s *RepositoriesService) ListByOrg(org string, opt *RepositoryListByOrgOpti
 }
 
 // Get fetches a repository.
+//
+// GitHub API docs: http://developer.github.com/v3/repos/#get
 func (s *RepositoriesService) Get(owner, repo string) (*Repository, error) {
 	url_ := fmt.Sprintf("repos/%v/%v", owner, repo)
 	req, err := s.client.NewRequest("GET", url_, nil)

github/users.go

@@ -21,6 +21,7 @@ type UsersService struct {
 	client *Client
 }
 
+// User represents a GitHub user.
 type User struct {
 	Login       string     `json:"login,omitempty"`
 	ID          int        `json:"id,omitempty"`
@@ -41,6 +42,8 @@ type User struct {
 
 // Get fetches a user.  Passing the empty string will fetch the authenticated
 // user.
+//
+// GitHub API docs: http://developer.github.com/v3/users/#get-a-single-user
 func (s *UsersService) Get(user string) (*User, error) {
 	var url_ string
 	if user != "" {
@@ -59,6 +62,8 @@ func (s *UsersService) Get(user string) (*User, error) {
 }
 
 // Edit the authenticated user.
+//
+// GitHub API docs: http://developer.github.com/v3/users/#update-the-authenticated-user
 func (s *UsersService) Edit(user *User) (*User, error) {
 	url_ := "user"
 	req, err := s.client.NewRequest("PATCH", url_, user)
@@ -71,14 +76,16 @@ func (s *UsersService) Edit(user *User) (*User, error) {
 	return u, err
 }
 
-// UserListOptions specifies optional paramters to the UsersService.List
+// UserListOptions specifies optional parameters to the UsersService.List
 // method.
 type UserListOptions struct {
 	// ID of the last user seen
 	Since int
 }
 
-// List all users.
+// ListAll lists all GitHub users.
+//
+// GitHub API docs: http://developer.github.com/v3/users/#get-all-users
 func (s *UsersService) ListAll(opt *UserListOptions) ([]User, error) {
 	url_ := "users"
 	if opt != nil {