From 2e1d27a8ce701d3597d6703bc861f71d4895bc47 Mon Sep 17 00:00:00 2001
From: Phill MV <phillmv@github.com>
Date: Fri, 22 Mar 2024 12:07:37 -0400
Subject: [PATCH] Tweaked docstrings for gh attestation download

---
 pkg/cmd/attestation/attestation.go       | 14 ++-------
 pkg/cmd/attestation/download/download.go | 38 ++++++++++++------------
 2 files changed, 21 insertions(+), 31 deletions(-)

diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go
index aa445f71a..9b3a0cd2c 100644
--- a/pkg/cmd/attestation/attestation.go
+++ b/pkg/cmd/attestation/attestation.go
@@ -7,26 +7,16 @@ import (
 	"github.com/cli/cli/v2/pkg/cmd/attestation/verify"
 	"github.com/cli/cli/v2/pkg/cmdutil"
 
-	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 )
 
 func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command {
 	root := &cobra.Command{
 		Use:     "attestation [subcommand]",
-		Short:   "Work with attestations",
+		Short:   "Work with artifact attestations",
 		Aliases: []string{"at"},
 		Hidden:  true,
-		Long: heredoc.Docf(`
-		Work with attestations that represent trusted metadata about artifacts and images.
-
-		The %[1]sattestation%[1]s command and all subcommands support the following account types:
-		* Free tier
-		* Pro tier
-		* Team tier
-		* GHEC
-		* GHEC EMU
-	`, "`"),
+		Long:    "Download and verify artifact attestations.",
 	}
 
 	root.AddCommand(download.NewDownloadCmd(f, nil))
diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go
index bf9b12894..2f40970fc 100644
--- a/pkg/cmd/attestation/download/download.go
+++ b/pkg/cmd/attestation/download/download.go
@@ -19,42 +19,42 @@ import (
 func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command {
 	opts := &Options{}
 	downloadCmd := &cobra.Command{
-		Use:   "download [<file path> | oci://<OCI image URI>]",
+		Use:   "download [<file-path> | oci://<image-uri>] [--owner | --repo]",
 		Args:  cobra.ExactArgs(1),
 		Short: "Download an artifact's Sigstore bundle(s) for offline use",
 		Long: heredoc.Docf(`
-			Download an artifact's Sigstore bundle(s) for offline use.
-			
+			Download an artifact's attestations, aka Sigstore bundle(s), for offline use.
+
 			The command requires either:
-			* a relative path to a local artifact, or
-			* a container image URI (e.g. %[1]soci://<my-OCI-image-URI>%[1]s)
+			* a file path to an artifact, or
+			* a container image URI (e.g. %[1]soci://<image-uri>%[1]s)
 
-			Note that if you provide an OCI URI for the artifact you must already
-			be authenticated with a container registry.
+			(Note that if you provide an OCI URL, you must already be authenticated with
+			its container registry.)
 
-			In addition, the command also requires either:
-			* the %[1]s--owner%[1]s flag (e.g. github), or
-			* the %[1]s--repo%[1]s flag (e.g. github/example).
+			In addition, the command requires either:
+			* the %[1]s--owner%[1]s flag (e.g. --owner github), or
+			* the %[1]s--repo%[1]s flag (e.g. --repo github/example).
 
-			The value of the %[1]s--owner%[1]s flag must match the name of the GitHub
-			organization that the artifact is associated with.
+			The %[1]s--owner%[1]s flag value must match the name of the GitHub organization
+			that the artifact is associated with.
 
-			The value of the %[1]s--repo%[1]s flag must match the name of the GitHub
-			repository that the artifact is associated with.
+			The %[1]s--repo%[1]s flag value must match the name of the GitHub repository
+			that the artifact is associated with.
 
-			The corresponding Sigstore bundle(s) will be written to a file in the
+			Any associated Sigstore bundle(s) will be written to a file in the
 			current directory named after the artifact's digest. For example, if the
-			artifact's digest is "sha256:1234", the file will be named "sha256:1234.jsonl".
+			digest is "sha256:1234", the file will be named "sha256:1234.jsonl".
 		`, "`"),
 		Example: heredoc.Doc(`
 			# Download Sigstore bundle(s) for a local artifact associated with a GitHub organization
-			$ gh attestation download <my-artifact> -o <GitHub organization>
+			$ gh attestation download example.bin -o github
 
 			# Download Sigstore bundle(s) for a local artifact associated with a GitHub repository
-			$ gh attestation download <my-artifact> -R <GitHub repo>
+			$ gh attestation download example.bin -R github/example
 
 			# Download Sigstore bundle(s) for an OCI image associated with a GitHub organization
-			$ gh attestation download oci://<my-OCI-image> -o <GitHub organization>
+			$ gh attestation download oci://example.com/foo/bar:latest -o github
 		`),
 		// PreRunE is used to validate flags before the command is run
 		// If an error is returned, its message will be printed to the terminal