docs: Improve comments in /examples (#4122)

Author: alexandear

example/codespaces/newreposecretwithxcrypto/main.go

@@ -100,27 +100,27 @@ func getSecretValue(secretName string) (string, error) {
 
 // addRepoSecret will add a secret to a GitHub repo for use in GitHub Codespaces.
 //
-// The secretName and secretValue will determine the name of the secret added and it's corresponding value.
+// The secretName and secretValue determine the name of the secret added and its corresponding value.
 //
-// The actual transmission of the secret value to GitHub using the api requires that the secret value is encrypted
+// The actual transmission of the secret value to GitHub using the API requires that the secret value is encrypted
 // using the public key of the target repo. This encryption is done using x/crypto/nacl/box.
 //
 // First, the public key of the repo is retrieved. The public key comes base64
 // encoded, so it must be decoded prior to use.
 //
-// Second, the decode key is converted into a fixed size byte array.
+// Second, the decoded key is converted into a fixed-size byte array.
 //
 // Third, the secret value is converted into a slice of bytes.
 //
 // Fourth, the secret is encrypted with box.SealAnonymous using the repo's decoded public key.
 //
-// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncodedSecret type.
+// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncryptedSecret type.
 //
-// Sixth, The other two properties of the github.EncodedSecret type are determined. The name of the secret to be added
+// Sixth, the other two properties of the github.EncryptedSecret type are determined: the name of the secret to be added
 // (string not base64), and the KeyID of the public key used to encrypt the secret.
 // This can be retrieved via the public key's GetKeyID method.
 //
-// Finally, the github.EncodedSecret is passed into the GitHub client.Codespaces.CreateOrUpdateRepoSecret method to
+// Finally, the github.EncryptedSecret is passed into the GitHub client.Codespaces.CreateOrUpdateRepoSecret method to
 // populate the secret in the GitHub repo.
 func addRepoSecret(ctx context.Context, client *github.Client, owner, repo, secretName, secretValue string) error {
 	publicKey, _, err := client.Codespaces.GetRepoPublicKey(ctx, owner, repo)

example/codespaces/newusersecretwithxcrypto/main.go

@@ -93,27 +93,27 @@ func getSecretValue(secretName string) (string, error) {
 
 // addUserSecret will add a secret to a GitHub user for use in GitHub Codespaces.
 //
-// The secretName and secretValue will determine the name of the secret added and it's corresponding value.
+// The secretName and secretValue determine the name of the secret added and its corresponding value.
 //
-// The actual transmission of the secret value to GitHub using the api requires that the secret value is encrypted
+// The actual transmission of the secret value to GitHub using the API requires that the secret value is encrypted
 // using the public key of the target user. This encryption is done using x/crypto/nacl/box.
 //
 // First, the public key of the user is retrieved. The public key comes base64
 // encoded, so it must be decoded prior to use.
 //
-// Second, the decode key is converted into a fixed size byte array.
+// Second, the decoded key is converted into a fixed-size byte array.
 //
 // Third, the secret value is converted into a slice of bytes.
 //
 // Fourth, the secret is encrypted with box.SealAnonymous using the user's decoded public key.
 //
-// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncodedSecret type.
+// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncryptedSecret type.
 //
-// Sixth, The other two properties of the github.EncodedSecret type are determined. The name of the secret to be added
+// Sixth, the other two properties of the github.EncryptedSecret type are determined: the name of the secret to be added
 // (string not base64), and the KeyID of the public key used to encrypt the secret.
 // This can be retrieved via the public key's GetKeyID method.
 //
-// Seventh, the github.EncodedSecret is passed into the GitHub client.Codespaces.CreateOrUpdateUserSecret method to
+// Seventh, the github.EncryptedSecret is passed into the GitHub client.Codespaces.CreateOrUpdateUserSecret method to
 // populate the secret in the GitHub user.
 //
 // Finally, if a repo and owner are passed in, it adds the repo to the user secret.

example/listenvironments/main.go

@@ -6,7 +6,7 @@
 // listenvironments is an example of how to use ListEnvironments method with EnvironmentListOptions.
 // It's runnable with the following command:
 //
-//	export GITHUB_TOKEN=your_token
+//	export GITHUB_AUTH_TOKEN=your_token
 //	export GITHUB_REPOSITORY_OWNER=your_owner
 //	export GITHUB_REPOSITORY_NAME=your_repo
 //	go run .

example/newfilewithappauth/main.go

@@ -4,8 +4,8 @@
 // license that can be found in the LICENSE file.
 
 // newfilewithappauth demonstrates the functionality of GitHub's app authentication
-// methods by fetching an installation access token and reauthenticating to GitHub
-// with OAuth configurations.
+// methods by fetching an installation access token as a GitHub App and then
+// using that token to authenticate with the GitHub API.
 package main
 
 import (

example/newreposecretwithxcrypto/main.go

@@ -100,27 +100,27 @@ func getSecretValue(secretName string) (string, error) {
 
 // addRepoSecret will add a secret to a GitHub repo for use in GitHub Actions.
 //
-// The secretName and secretValue will determine the name of the secret added and it's corresponding value.
+// The secretName and secretValue determine the name of the secret added and its corresponding value.
 //
-// The actual transmission of the secret value to GitHub using the api requires that the secret value is encrypted
+// The actual transmission of the secret value to GitHub using the API requires that the secret value is encrypted
 // using the public key of the target repo. This encryption is done using x/crypto/nacl/box.
 //
 // First, the public key of the repo is retrieved. The public key comes base64
 // encoded, so it must be decoded prior to use.
 //
-// Second, the decode key is converted into a fixed size byte array.
+// Second, the decoded key is converted into a fixed-size byte array.
 //
 // Third, the secret value is converted into a slice of bytes.
 //
 // Fourth, the secret is encrypted with box.SealAnonymous using the repo's decoded public key.
 //
-// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncodedSecret type.
+// Fifth, the encrypted secret is encoded as a base64 string to be used in a github.EncryptedSecret type.
 //
-// Sixth, The other two properties of the github.EncodedSecret type are determined. The name of the secret to be added
+// Sixth, the other two properties of the github.EncryptedSecret type are determined: the name of the secret to be added
 // (string not base64), and the KeyID of the public key used to encrypt the secret.
 // This can be retrieved via the public key's GetKeyID method.
 //
-// Finally, the github.EncodedSecret is passed into the GitHub client.Actions.CreateOrUpdateRepoSecret method to
+// Finally, the github.EncryptedSecret is passed into the GitHub client.Actions.CreateOrUpdateRepoSecret method to
 // populate the secret in the GitHub repo.
 func addRepoSecret(ctx context.Context, client *github.Client, owner, repo, secretName, secretValue string) error {
 	publicKey, _, err := client.Actions.GetRepoPublicKey(ctx, owner, repo)

example/otel/main.go

@@ -56,7 +56,7 @@ func main() {
 			limits.GetCore().Reset)
 	}
 
-	// Check if we captured attributes in response
+	// Print the HTTP response status when available.
 	if resp != nil {
 		fmt.Printf("Response Status: %v\n", resp.Status)
 	}

example/ratelimit/main.go

@@ -3,8 +3,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The ratelimit command demonstrates using the github_ratelimit as well as github_pagination.
-// By using the waiter, the client automatically sleeps and retry requests
+// The ratelimit command demonstrates using github_ratelimit and github_pagination.
+// By using the waiters, the client automatically sleeps and retries requests
 // when it hits secondary rate limits.
 // It also prevents the client from abusing the API in case of a primary rate limit.
 package main
@@ -39,7 +39,7 @@ func main() {
 	)
 	client := github.NewClient(paginator)
 
-	// arbitrary usage of the client
+	// Example usage of the client
 	repos, _, err := client.Repositories.ListByUser(context.Background(), username, nil)
 	if err != nil {
 		fmt.Printf("Error: %v\n", err)

example/topics/main.go

@@ -3,7 +3,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The simple command demonstrates the functionality that
+// The topics command demonstrates the functionality that
 // prompts the user for a GitHub topic and lists all the entities
 // that are related to the specified topic or subject.
 package main

example/verifyartifact/main.go

@@ -3,8 +3,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This is a simple example of how to verify an artifact
-// attestations hosted on GitHub using the sigstore-go library.
+// This is a simple example of how to verify artifact attestations
+// hosted on GitHub using the sigstore-go library.
 // This is a very barebones example drawn from the sigstore-go
 // library's examples and should not be used in production.
 package main
@@ -30,10 +30,10 @@ var (
 	// compute the digest.
 	artifactDigest = flag.String("artifact-digest", "", "The digest of the artifact")
 	// The algorithm used to compute the digest of the artifact.
-	// Note that the GitHub API only currently support querying
+	// Note that the GitHub API currently only supports querying
 	// by sha256 digest.
 	artifactDigestAlgorithm = flag.String("artifact-digest-algorithm", "sha256", "The algorithm used to compute the digest of the artifact")
-	// Attestations produced by GitHub Actions use ID token
+	// Attestations produced by GitHub Actions use ID tokens
 	// issued by GitHub.
 	expectedIssuer = flag.String("expected-issuer", "https://token.actions.githubusercontent.com", "Issuer of the OIDC token")
 	// Subject Alternative Name is set to the calling workflow file.