refactor(actions): trim help examples and restating comments

Signed-off-by: bircni <bircni@icloud.com>

internal/app/action_logs.go

@@ -34,8 +34,6 @@ prefixing each line with its job's name when it follows several jobs. With --out
 it downloads the logs of the whole run as a ZIP archive instead.`,
 		Example: `# print the logs of every job of a run
 $ tea run logs 34
-# print the logs of the failed jobs
-$ tea run logs 34 --failed
 # follow the logs of one job while it runs
 $ tea run logs 34 --job build --follow
 # download the logs as a ZIP archive

internal/app/action_runs.go

@@ -185,8 +185,6 @@ func (a *application) runViewCommand() *cobra.Command {
 		Long:  "View a workflow run with its jobs and their steps.",
 		Example: `# view a run with its jobs and steps
 $ tea run view 34
-# view a run from its URL
-$ tea run view https://gitea.example.com/alice/project/actions/runs/34
 # print the logs of every job of a run
 $ tea run view 34 --log
 # get the conclusion of each job as JSON
@@ -481,9 +479,8 @@ $ tea run watch 34 --timeout 10m && echo deployed`,
 	return cmd
 }
 
-// watchRun polls run id until it completes. A terminal shows the run view, redrawn in place on
+// watchRun polls run id until it completes, redrawing the run view on the alternate screen of a
-// the alternate screen, then the final view and a summary; otherwise each change of state is
+// terminal, or else reporting each change of state on stderr.
-// reported on stderr, and the completed run printed. It fails when the run does not succeed.
 func (a *application) watchRun(cmd *cobra.Command, t target, id int64, interval, timeout time.Duration) error {
 	ctx, cancel := context.WithTimeout(cmd.Context(), timeout)
 	defer cancel()
@@ -661,7 +658,6 @@ func (a *application) unfinished(t target, run services.Run) error {
 	return fmt.Errorf("run %d is still %s; cancel it first: tea run cancel %d%s", run.ID, run.Status, run.ID, a.suggestedRepo(t))
 }
 
-// findJob returns the job of run that raw names by ID or name.
 func findJob(jobs []services.Job, raw string, run int64) (services.Job, error) {
 	return services.NameOrID[services.Job]{
 		Kind: "job", Scope: fmt.Sprintf("run %d", run),

internal/app/action_values.go

@@ -67,17 +67,6 @@ func (f *actionScopeFlags) resolve(a *application, cmd *cobra.Command) (services
 	return scope, t, nil
 }
 
-// actionValueLong explains the scopes of secrets or variables.
-func actionValueLong(kind, use string) string {
-	return fmt.Sprintf(`Manage the Actions %[1]ss that workflows %[2]s.
-
-A %[1]s belongs to a repository, to an organization (--org), whose repositories all see it, or
-to your user account (--account), which all your repositories see. Without --org or --account,
-tea uses the repository of the working directory or --repo. Names are stored upper-cased.
-
-Note that the global --user flag selects the account tea acts as, not a scope.`, kind, use)
-}
-
 func (a *application) actionValueCommand(secret bool) *cobra.Command {
 	kind, use := "variable", "read with ${{ vars.NAME }}"
 	if secret {
@@ -86,7 +75,13 @@ func (a *application) actionValueCommand(secret bool) *cobra.Command {
 	group := &cobra.Command{
 		Use:   kind,
 		Short: fmt.Sprintf("Manage Actions %ss for a repository, organization, or your account", kind),
-		Long:  actionValueLong(kind, use),
+		Long: fmt.Sprintf(`Manage the Actions %[1]ss that workflows %[2]s.
+
+A %[1]s belongs to a repository, to an organization (--org), whose repositories all see it, or
+to your user account (--account), which all your repositories see. Without --org or --account,
+tea uses the repository of the working directory or --repo. Names are stored upper-cased.
+
+Note that the global --user flag selects the account tea acts as, not a scope.`, kind, use),
 	}
 	group.AddCommand(a.actionValueListCommand(secret, kind), a.actionValueSetCommand(secret, kind), a.actionValueDeleteCommand(secret, kind))
 	if !secret {
@@ -178,8 +173,6 @@ $ tea variable set --env-file .env`
 $ tea secret set DEPLOY_TOKEN
 # set an organization secret from standard input
 $ echo -n "$TOKEN" | tea secret set NPM_TOKEN --org acme
-# set a secret of your account from a file
-$ tea secret set SSH_KEY --account --body-file key.pem
 # set the secrets of a dotenv file
 $ tea secret set --env-file .env`
 	}

internal/app/actions.go

@@ -57,7 +57,6 @@ $ tea workflow list --json id,state --jq '.[] | select(.state != "active") | .id
 	}
 }
 
-// workflowColumns head workflowRow.
 var workflowColumns = []terminal.Column{{Header: "Name", Flex: true}, {Header: "File"}, {Header: "State"}, {Header: "Path", PipedOnly: true}, {Header: "URL", PipedOnly: true}}
 
 func workflowRow(item services.Workflow) []terminal.Cell {
@@ -129,7 +128,6 @@ $ tea workflow view ci --web`,
 	return cmd
 }
 
-// renderWorkflow shows a workflow with its recent runs.
 func (a *application) renderWorkflow(t target, workflow services.Workflow, runs []services.Run) string {
 	d := a.display()
 	rows := make([][]terminal.Cell, len(runs))
@@ -279,7 +277,6 @@ func (a *application) nextStep(cmd *cobra.Command, format string, args ...any) {
 	}
 }
 
-// inputValues parses key=value workflow inputs.
 func inputValues(fields []string) (map[string]string, error) {
 	values := map[string]string{}
 	for _, field := range fields {

internal/app/download.go

@@ -21,7 +21,6 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// downloadFlags are the destination flags of a download command.
 type downloadFlags struct {
 	// output is a file, an existing directory to download into, or - for standard output.
 	output string
@@ -31,8 +30,6 @@ type downloadFlags struct {
 	clobber, skipExisting bool
 }
 
-// register adds -O/--output (and its older name --output-file), -D/--dir, --clobber and
-// --skip-existing to cmd.
 func (f *downloadFlags) register(cmd *cobra.Command) {
 	flags := cmd.Flags()
 	flags.StringVarP(&f.output, "output", "O", "", "File or directory to write to, or - for standard output (default: the download's name)")
@@ -43,10 +40,8 @@ func (f *downloadFlags) register(cmd *cobra.Command) {
 	flags.BoolVar(&f.skipExisting, "skip-existing", false, "Keep an existing file and skip the download")
 }
 
-// destination returns the path a download named name is written to: --output (inside it when it
+// destination returns where a download named name goes, or "-" for standard output. It fails
-// is a directory), else name inside --dir or the working directory, or "-" for standard
+// before anything is downloaded when the file exists without --clobber or --skip-existing.
-// output. skip reports an existing file that --skip-existing keeps. It fails before anything
-// is downloaded when the file exists without --clobber or --skip-existing.
 func (f downloadFlags) destination(name string) (path string, skip bool, err error) {
 	switch {
 	case f.output != "" && f.dir != "":

internal/app/notifications.go

@@ -340,7 +340,6 @@ func notificationsWith(statuses []string) string {
 	return distinct[0] + " or " + distinct[1] + " notifications"
 }
 
-// notificationStatus is unread, read or pinned.
 func notificationStatus(item services.Notification) string {
 	switch {
 	case item.Pinned:

internal/app/time.go

@@ -66,8 +66,7 @@ func (a *application) timeListCommand() *cobra.Command {
 	cmd := &cobra.Command{Use: "list", Short: "List tracked time", Long: `List the time tracked in a repository, on one issue with --issue, or by yourself across
 repositories with --mine. On a terminal, the total of the listed time follows the table.`, Example: `$ tea time list
 $ tea time list --issue 12
-$ tea time list --mine --since 168h
+$ tea time list --mine --since 168h`, Args: argsExact(0), RunE: func(cmd *cobra.Command, _ []string) error {
-$ tea time list --username @me --json issue_number,seconds`, Args: argsExact(0), RunE: func(cmd *cobra.Command, _ []string) error {
 		if (opts.Mine && (issue != "" || opts.Username != "")) || (issue != "" && opts.Username != "") {
 			return clierr.Wrap(clierr.Usage, errors.New("--mine, --issue and --username select mutually exclusive scopes"))
 		}

internal/app/webhooks.go

@@ -55,13 +55,11 @@ func collapsedEvents(events []string) string {
 	return strings.Join(shown, ", ")
 }
 
-// webhookScope holds the scope flags of the webhook commands.
 type webhookScope struct {
 	org             string
 	account, global bool
 }
 
-// service resolves the target and the webhooks of the selected scope.
 func (s *webhookScope) service(a *application, cmd *cobra.Command) (target, services.Webhooks, error) {
 	scopes := 0
 	for _, selected := range []bool{s.org != "", s.account, s.global, a.options.repo != ""} {
@@ -89,7 +87,6 @@ func webhookScopeName(scope services.WebhookScope) string {
 	return scope.Repository
 }
 
-// webhookSettingsURL is the settings page of a webhook.
 func webhookSettingsURL(t target, scope services.WebhookScope, id int64) string {
 	hook := strconv.FormatInt(id, 10)
 	switch {
@@ -361,10 +358,8 @@ $ tea webhook create https://hooks.slack.com/services/T0/B0/X --org acme --type
 			return err
 		}
 		askAuthorization := !create && authSources == 0
-		if askAuthorization {
+		if askAuthorization && !a.canPrompt() {
-			if !a.canPrompt() {
+			return clierr.Wrap(clierr.Usage, errors.New("editing a webhook drops its stored authorization header unless it is sent again, and Gitea never returns it: pass --authorization-header-file or --authorization-header (use --clear-authorization only for a hook without one)"))
-				return clierr.Wrap(clierr.Usage, errors.New("editing a webhook drops its stored authorization header unless it is sent again, and Gitea never returns it: pass --authorization-header-file or --authorization-header (use --clear-authorization only for a hook without one)"))
-			}
 		}
 		if strings.ContainsAny(authorization, "\r\n") {
 			return clierr.Wrap(clierr.Usage, errors.New("authorization header must be a single line"))

internal/app/wiki.go

@@ -26,7 +26,6 @@ func (a *application) wikiCommand() *cobra.Command {
 	return group
 }
 
-// completeWikiPages completes the titles of the repository's wiki pages.
 func (a *application) completeWikiPages() cobra.CompletionFunc {
 	return a.apiCompletion(true, func(ctx context.Context, t target, _ string) ([]cobra.Completion, error) {
 		pages, err := services.Wiki{Client: t.client, Repository: t.Repo}.ListPage(ctx, completionLimit, 1)
@@ -92,7 +91,6 @@ func (a *application) wikiViewCommand() *cobra.Command {
 	return command
 }
 
-// wikiView shows a wiki page with its content as the body.
 func (a *application) wikiView(item services.WikiPage) terminal.View {
 	var meta []string
 	if item.Author != "" {
@@ -138,7 +136,7 @@ func (a *application) wikiRevisionsCommand() *cobra.Command {
 				},
 				Context: "revisions of wiki page " + strconv.Quote(args[0]), Empty: "no revisions of wiki page " + strconv.Quote(args[0]),
 			}
-			return writeTable(a, cmd, items, spec, listPage{Number: page, Counted: false, More: false})
+			return writeTable(a, cmd, items, spec, listPage{Number: page})
 		},
 	}
 	positiveIntVar(command, &page, "page", 1, math.MaxInt, "Revision page (server controls page size)")