docs: Extend the description of ref parameters (#3643)

Author: alexandear

example/commitpr/main.go

@@ -63,7 +63,7 @@ var ctx = context.Background()
 // getRef returns the commit branch reference object if it exists or creates it
 // from the base branch before returning it.
 func getRef() (ref *github.Reference, err error) {
-	if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*commitBranch); err == nil {
+	if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*commitBranch)); err == nil {
 		return ref, nil
 	}
 
@@ -78,14 +78,19 @@ func getRef() (ref *github.Reference, err error) {
 	}
 
 	var baseRef *github.Reference
-	if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*baseBranch); err != nil {
+	if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*baseBranch)); err != nil {
 		return nil, err
 	}
-	newRef := &github.Reference{Ref: github.Ptr("refs/heads/" + *commitBranch), Object: &github.GitObject{SHA: baseRef.Object.SHA}}
+	newRef := &github.Reference{Ref: github.Ptr(branchRef(*commitBranch)), Object: &github.GitObject{SHA: baseRef.Object.SHA}}
 	ref, _, err = client.Git.CreateRef(ctx, *sourceOwner, *sourceRepo, newRef)
 	return ref, err
 }
 
+// branchRef generates the fully qualified git reference for the given branch name.
+func branchRef(name string) string {
+	return "refs/heads/" + name
+}
+
 // getTree generates the tree to commit based on the given files and the commit
 // of the ref you got in getRef.
 func getTree(ref *github.Reference) (tree *github.Tree, err error) {

github/checks.go

@@ -269,6 +269,8 @@ type ListCheckRunsResults struct {
 }
 
 // ListCheckRunsForRef lists check runs for a specific ref.
+// The ref can be a commit SHA, branch name `heads/<branch name>`, or tag name `tags/<tag name>`.
+// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References.
 //
 // GitHub API docs: https://docs.github.com/rest/checks/runs#list-check-runs-for-a-git-reference
 //
@@ -357,6 +359,8 @@ type ListCheckSuiteResults struct {
 }
 
 // ListCheckSuitesForRef lists check suite for a specific ref.
+// The ref can be a commit SHA, branch name `heads/<branch name>`, or tag name `tags/<tag name>`.
+// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References.
 //
 // GitHub API docs: https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference
 //

github/git_refs.go

@@ -14,6 +14,7 @@ import (
 
 // Reference represents a GitHub reference.
 type Reference struct {
+	// The name of the fully qualified reference, i.e.: `refs/heads/master`.
 	Ref    *string    `json:"ref"`
 	URL    *string    `json:"url"`
 	Object *GitObject `json:"object"`
@@ -48,6 +49,7 @@ type updateRefRequest struct {
 }
 
 // GetRef fetches a single reference in a repository.
+// The ref must be formatted as `heads/<branch name>` for branches and `tags/<tag name>` for tags.
 //
 // GitHub API docs: https://docs.github.com/rest/git/refs#get-a-reference
 //
@@ -82,6 +84,7 @@ func refURLEscape(ref string) string {
 // ReferenceListOptions specifies optional parameters to the
 // GitService.ListMatchingRefs method.
 type ReferenceListOptions struct {
+	// The ref must be formatted as `heads/<branch name>` for branches and `tags/<tag name>` for tags.
 	Ref string `url:"-"`
 
 	ListOptions

github/repos_deployments.go

@@ -49,7 +49,7 @@ type DeploymentsListOptions struct {
 	// SHA of the Deployment.
 	SHA string `url:"sha,omitempty"`
 
-	// List deployments for a given ref.
+	// List deployments for a given ref. This can be a branch, tag, or SHA.
 	Ref string `url:"ref,omitempty"`
 
 	// List deployments for a given task.

github/repos_statuses.go

@@ -43,7 +43,7 @@ func (r RepoStatus) String() string {
 }
 
 // ListStatuses lists the statuses of a repository at the specified
-// reference. ref can be a SHA, a branch name, or a tag name.
+// reference. The ref can be a SHA, a branch name, or a tag name.
 //
 // GitHub API docs: https://docs.github.com/rest/commits/statuses#list-commit-statuses-for-a-reference
 //
@@ -70,7 +70,7 @@ func (s *RepositoriesService) ListStatuses(ctx context.Context, owner, repo, ref
 }
 
 // CreateStatus creates a new status for a repository at the specified
-// reference. Ref can be a SHA, a branch name, or a tag name.
+// reference. The ref can be a SHA, a branch name, or a tag name.
 //
 // GitHub API docs: https://docs.github.com/rest/commits/statuses#create-a-commit-status
 //
@@ -111,7 +111,7 @@ func (s CombinedStatus) String() string {
 }
 
 // GetCombinedStatus returns the combined status of a repository at the specified
-// reference. ref can be a SHA, a branch name, or a tag name.
+// reference. The ref can be a SHA, a branch name, or a tag name.
 //
 // GitHub API docs: https://docs.github.com/rest/commits/statuses#get-the-combined-status-for-a-specific-reference
 //