From 0a2d3032cf5f2ce0eba43f84a1394dae4b94844e Mon Sep 17 00:00:00 2001 From: Oleksandr Redko Date: Mon, 9 Jun 2025 15:26:49 +0300 Subject: [PATCH] docs: Use pkgsite links --- github/doc.go | 30 +++++++++++++++--------------- github/github.go | 10 +++++----- github/messages.go | 40 ++++++++++++++++++++-------------------- 3 files changed, 40 insertions(+), 40 deletions(-) diff --git a/github/doc.go b/github/doc.go index 8a6112fe9e7..a9f36f0979c 100644 --- a/github/doc.go +++ b/github/doc.go @@ -31,27 +31,27 @@ The services of a client divide the API into logical chunks and correspond to the structure of the GitHub API documentation at https://docs.github.com/rest . -NOTE: Using the https://pkg.go.dev/context package, one can easily +NOTE: Using the [context] package, one can easily pass cancelation signals and deadlines to various services of the client for -handling a request. In case there is no context available, then context.Background() +handling a request. In case there is no context available, then [context.Background] can be used as a starting point. For more sample code snippets, head over to the https://github.com/google/go-github/tree/master/example directory. # Authentication -Use Client.WithAuthToken to configure your client to authenticate using an Oauth token +Use [Client.WithAuthToken] to configure your client to authenticate using an Oauth token (for example, a personal access token). This is what is needed for a majority of use cases aside from GitHub Apps. client := github.NewClient(nil).WithAuthToken("... your access token ...") -Note that when using an authenticated Client, all calls made by the client will +Note that when using an authenticated [Client], all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users. For API methods that require HTTP Basic Authentication, use the -BasicAuthTransport. +[BasicAuthTransport]. GitHub Apps authentication can be provided by the https://github.com/bradleyfalzon/ghinstallation package. @@ -100,15 +100,15 @@ limited to 60 requests per hour, while authenticated clients can make up to clients are limited to 10 requests per minute, while authenticated clients can make up to 30 requests per minute. To receive the higher rate limit when making calls that are not issued on behalf of a user, -use UnauthenticatedRateLimitedTransport. +use [UnauthenticatedRateLimitedTransport]. -The returned Response.Rate value contains the rate limit information +The returned [Response].[Rate] value contains the rate limit information from the most recent API call. If a recent enough response isn't available, you can use RateLimits to fetch the most up-to-date rate limit data for the client. -To detect an API rate limit error, you can check if its type is *github.RateLimitError. -For secondary rate limits, you can check if its type is *github.AbuseRateLimitError: +To detect an API rate limit error, you can check if its type is *[RateLimitError]. +For secondary rate limits, you can check if its type is *[AbuseRateLimitError]: repos, _, err := client.Repositories.List(ctx, "", nil) if _, ok := err.(*github.RateLimitError); ok { @@ -129,7 +129,7 @@ the GitHub side. Methods known to behave like this are documented specifying this behavior. To detect this condition of error, you can check if its type is -*github.AcceptedError: +*[AcceptedError]: stats, _, err := client.Repositories.ListContributorsStats(ctx, org, repo) if _, ok := err.(*github.AcceptedError); ok { @@ -142,7 +142,7 @@ The GitHub REST API has good support for conditional HTTP requests via the ETag header which will help prevent you from burning through your rate limit, as well as help speed up your application. go-github does not handle conditional requests directly, but is instead designed to work with a -caching http.Transport. +caching [http.Transport]. Typically, an RFC 7234 compliant HTTP cache such as https://github.com/gregjones/httpcache is recommended. Alternatively, the https://github.com/bored-engineer/github-conditional-http-transport @@ -157,7 +157,7 @@ https://docs.github.com/rest/overview/resources-in-the-rest-api#conditional-requ All structs for GitHub resources use pointer values for all non-repeated fields. This allows distinguishing between unset fields and those set to a zero-value. -Helper functions have been provided to easily create these pointers for string, +A helper function, [Ptr], has been provided to easily create these pointers for string, bool, and int values. For example: // create a new private repository named "foo" @@ -173,10 +173,10 @@ Users who have worked with protocol buffers should find this pattern familiar. All requests for resource collections (repos, pull requests, issues, etc.) support pagination. Pagination options are described in the -github.ListOptions struct and passed to the list methods directly or as an +[ListOptions] struct and passed to the list methods directly or as an embedded type of a more specific list options struct (for example -github.PullRequestListOptions). Pages information is available via the -github.Response struct. +[PullRequestListOptions]). Pages information is available via the +[Response] struct. client := github.NewClient(nil) diff --git a/github/github.go b/github/github.go index 513f9fe4bcd..b2e8c863b1a 100644 --- a/github/github.go +++ b/github/github.go @@ -1393,12 +1393,12 @@ func (e *Error) UnmarshalJSON(data []byte) error { // present. A response is considered an error if it has a status code outside // the 200 range or equal to 202 Accepted. // API error responses are expected to have response -// body, and a JSON response body that maps to ErrorResponse. +// body, and a JSON response body that maps to [ErrorResponse]. // -// The error type will be *RateLimitError for rate limit exceeded errors, -// *AcceptedError for 202 Accepted status codes, -// *TwoFactorAuthError for two-factor authentication errors, -// and *RedirectionError for redirect status codes (only happens when ignoring redirections). +// The error type will be *[RateLimitError] for rate limit exceeded errors, +// *[AcceptedError] for 202 Accepted status codes, +// *[TwoFactorAuthError] for two-factor authentication errors, +// and *[RedirectionError] for redirect status codes (only happens when ignoring redirections). func CheckResponse(r *http.Response) error { if r.StatusCode == http.StatusAccepted { return &AcceptedError{} diff --git a/github/messages.go b/github/messages.go index 95cb94b0eb5..21eb7c70c37 100644 --- a/github/messages.go +++ b/github/messages.go @@ -186,11 +186,11 @@ func messageMAC(signature string) ([]byte, func() hash.Hash, error) { // Example usage: // // func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) { -// // read signature from request -// signature := "" -// payload, err := github.ValidatePayloadFromBody(r.Header.Get("Content-Type"), r.Body, signature, s.webhookSecretKey) -// if err != nil { ... } -// // Process payload... +// // read signature from request +// signature := "" +// payload, err := github.ValidatePayloadFromBody(r.Header.Get("Content-Type"), r.Body, signature, s.webhookSecretKey) +// if err != nil { ... } +// // Process payload... // } func ValidatePayloadFromBody(contentType string, readable io.Reader, signature string, secretToken []byte) (payload []byte, err error) { var body []byte // Raw body that GitHub uses to calculate the signature. @@ -249,9 +249,9 @@ func ValidatePayloadFromBody(contentType string, readable io.Reader, signature s // Example usage: // // func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) { -// payload, err := github.ValidatePayload(r, s.webhookSecretKey) -// if err != nil { ... } -// // Process payload... +// payload, err := github.ValidatePayload(r, s.webhookSecretKey) +// if err != nil { ... } +// // Process payload... // } func ValidatePayload(r *http.Request, secretToken []byte) (payload []byte, err error) { signature := r.Header.Get(SHA256SignatureHeader) @@ -300,23 +300,23 @@ func DeliveryID(r *http.Request) string { // ParseWebHook parses the event payload. For recognized event types, a // value of the corresponding struct type will be returned (as returned -// by Event.ParsePayload()). An error will be returned for unrecognized event +// by [Event.ParsePayload]). An error will be returned for unrecognized event // types. // // Example usage: // // func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) { -// payload, err := github.ValidatePayload(r, s.webhookSecretKey) -// if err != nil { ... } -// event, err := github.ParseWebHook(github.WebHookType(r), payload) -// if err != nil { ... } -// switch event := event.(type) { -// case *github.CommitCommentEvent: -// processCommitCommentEvent(event) -// case *github.CreateEvent: -// processCreateEvent(event) -// ... -// } +// payload, err := github.ValidatePayload(r, s.webhookSecretKey) +// if err != nil { ... } +// event, err := github.ParseWebHook(github.WebHookType(r), payload) +// if err != nil { ... } +// switch event := event.(type) { +// case *github.CommitCommentEvent: +// processCommitCommentEvent(event) +// case *github.CreateEvent: +// processCreateEvent(event) +// ... +// } // } func ParseWebHook(messageType string, payload []byte) (any, error) { eventType, ok := messageToTypeName[messageType]