From 83bc80a1bb1c50a31138e3166e300ec4e3957031 Mon Sep 17 00:00:00 2001
From: Kynan Ware <47394200+BagToad@users.noreply.github.com>
Date: Wed, 4 Mar 2026 16:08:04 -0700
Subject: [PATCH] Add godoc comments to exported symbols in pkg/cmd/gist

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 pkg/cmd/gist/clone/clone.go   |  2 ++
 pkg/cmd/gist/create/create.go |  2 ++
 pkg/cmd/gist/delete/delete.go |  2 ++
 pkg/cmd/gist/edit/edit.go     |  2 ++
 pkg/cmd/gist/gist.go          |  1 +
 pkg/cmd/gist/list/list.go     |  2 ++
 pkg/cmd/gist/rename/rename.go |  2 ++
 pkg/cmd/gist/shared/shared.go | 13 +++++++++++++
 pkg/cmd/gist/view/view.go     |  2 ++
 9 files changed, 28 insertions(+)

diff --git a/pkg/cmd/gist/clone/clone.go b/pkg/cmd/gist/clone/clone.go
index c7db74521..d9306ba07 100644
--- a/pkg/cmd/gist/clone/clone.go
+++ b/pkg/cmd/gist/clone/clone.go
@@ -16,6 +16,7 @@ import (
 	ghauth "github.com/cli/go-gh/v2/pkg/auth"
 )
 
+// CloneOptions holds the options for the gist clone command.
 type CloneOptions struct {
 	HttpClient func() (*http.Client, error)
 	GitClient  *git.Client
@@ -27,6 +28,7 @@ type CloneOptions struct {
 	Gist      string
 }
 
+// NewCmdClone creates the gist clone command.
 func NewCmdClone(f *cmdutil.Factory, runF func(*CloneOptions) error) *cobra.Command {
 	opts := &CloneOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/create/create.go b/pkg/cmd/gist/create/create.go
index 06b2336b6..1eb637dc9 100644
--- a/pkg/cmd/gist/create/create.go
+++ b/pkg/cmd/gist/create/create.go
@@ -25,6 +25,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CreateOptions holds the options for the gist create command.
 type CreateOptions struct {
 	IO *iostreams.IOStreams
 
@@ -39,6 +40,7 @@ type CreateOptions struct {
 	Browser    browser.Browser
 }
 
+// NewCmdCreate creates the gist create command.
 func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Command {
 	opts := CreateOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/delete/delete.go b/pkg/cmd/gist/delete/delete.go
index 319f9265e..525a4425d 100644
--- a/pkg/cmd/gist/delete/delete.go
+++ b/pkg/cmd/gist/delete/delete.go
@@ -16,6 +16,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// DeleteOptions holds the options for the gist delete command.
 type DeleteOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -26,6 +27,7 @@ type DeleteOptions struct {
 	Confirmed bool
 }
 
+// NewCmdDelete creates the gist delete command.
 func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Command {
 	opts := DeleteOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/edit/edit.go b/pkg/cmd/gist/edit/edit.go
index 6f00c906c..311e4da32 100644
--- a/pkg/cmd/gist/edit/edit.go
+++ b/pkg/cmd/gist/edit/edit.go
@@ -25,6 +25,7 @@ import (
 
 var editNextOptions = []string{"Edit another file", "Submit", "Cancel"}
 
+// EditOptions holds the options for the gist edit command.
 type EditOptions struct {
 	IO         *iostreams.IOStreams
 	HttpClient func() (*http.Client, error)
@@ -41,6 +42,7 @@ type EditOptions struct {
 	Description    string
 }
 
+// NewCmdEdit creates the gist edit command.
 func NewCmdEdit(f *cmdutil.Factory, runF func(*EditOptions) error) *cobra.Command {
 	opts := EditOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/gist.go b/pkg/cmd/gist/gist.go
index 1f7fc9ea0..bc592f709 100644
--- a/pkg/cmd/gist/gist.go
+++ b/pkg/cmd/gist/gist.go
@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdGist creates the top-level gist command.
 func NewCmdGist(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "gist <command>",
diff --git a/pkg/cmd/gist/list/list.go b/pkg/cmd/gist/list/list.go
index 7582ca2cb..52e266138 100644
--- a/pkg/cmd/gist/list/list.go
+++ b/pkg/cmd/gist/list/list.go
@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ListOptions holds the options for the gist list command.
 type ListOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -28,6 +29,7 @@ type ListOptions struct {
 	Visibility     string // all, secret, public
 }
 
+// NewCmdList creates the gist list command.
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
 	opts := &ListOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/rename/rename.go b/pkg/cmd/gist/rename/rename.go
index 96f630c02..5598446aa 100644
--- a/pkg/cmd/gist/rename/rename.go
+++ b/pkg/cmd/gist/rename/rename.go
@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// RenameOptions holds the options for the gist rename command.
 type RenameOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -27,6 +28,7 @@ type RenameOptions struct {
 	NewFileName string
 }
 
+// NewCmdRename creates the gist rename command.
 func NewCmdRename(f *cmdutil.Factory, runf func(*RenameOptions) error) *cobra.Command {
 	opts := &RenameOptions{
 		IO:         f.IOStreams,
diff --git a/pkg/cmd/gist/shared/shared.go b/pkg/cmd/gist/shared/shared.go
index 305e2f642..987748037 100644
--- a/pkg/cmd/gist/shared/shared.go
+++ b/pkg/cmd/gist/shared/shared.go
@@ -19,6 +19,7 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
+// GistFile represents a single file within a gist.
 type GistFile struct {
 	Filename  string `json:"filename,omitempty"`
 	Type      string `json:"type,omitempty"`
@@ -28,10 +29,12 @@ type GistFile struct {
 	Truncated bool   `json:"truncated,omitempty"`
 }
 
+// GistOwner represents the owner of a gist.
 type GistOwner struct {
 	Login string `json:"login,omitempty"`
 }
 
+// Gist represents a GitHub gist and its metadata.
 type Gist struct {
 	ID          string               `json:"id,omitempty"`
 	Description string               `json:"description"`
@@ -42,6 +45,7 @@ type Gist struct {
 	Owner       *GistOwner           `json:"owner,omitempty"`
 }
 
+// Filename returns the alphabetically first filename in the gist.
 func (g Gist) Filename() string {
 	filenames := make([]string, 0, len(g.Files))
 	for fn := range g.Files {
@@ -54,12 +58,15 @@ func (g Gist) Filename() string {
 	return filenames[0]
 }
 
+// TruncDescription returns a truncated, whitespace-normalized description.
 func (g Gist) TruncDescription() string {
 	return text.Truncate(100, text.RemoveExcessiveWhitespace(g.Description))
 }
 
+// NotFoundErr is returned when a gist cannot be found.
 var NotFoundErr = errors.New("not found")
 
+// GetGist fetches a gist by ID from the GitHub API.
 func GetGist(client *http.Client, hostname, gistID string) (*Gist, error) {
 	gist := Gist{}
 	path := fmt.Sprintf("gists/%s", gistID)
@@ -77,6 +84,7 @@ func GetGist(client *http.Client, hostname, gistID string) (*Gist, error) {
 	return &gist, nil
 }
 
+// GistIDFromURL extracts the gist ID from a URL.
 func GistIDFromURL(gistURL string) (string, error) {
 	u, err := url.Parse(gistURL)
 	if err == nil && strings.HasPrefix(u.Path, "/") {
@@ -96,6 +104,7 @@ func GistIDFromURL(gistURL string) (string, error) {
 
 const maxPerPage = 100
 
+// ListGists retrieves gists for the authenticated user with optional filtering.
 func ListGists(client *http.Client, hostname string, limit int, filter *regexp.Regexp, includeContent bool, visibility string) ([]Gist, error) {
 	type response struct {
 		Viewer struct {
@@ -194,6 +203,7 @@ pagination:
 	return gists, nil
 }
 
+// IsBinaryFile reports whether the given file path contains binary content.
 func IsBinaryFile(file string) (bool, error) {
 	detectedMime, err := mimetype.DetectFile(file)
 	if err != nil {
@@ -210,6 +220,7 @@ func IsBinaryFile(file string) (bool, error) {
 	return isBinary, nil
 }
 
+// IsBinaryContents reports whether the given byte slice contains binary content.
 func IsBinaryContents(contents []byte) bool {
 	isBinary := true
 	for mime := mimetype.Detect(contents); mime != nil; mime = mime.Parent() {
@@ -221,6 +232,7 @@ func IsBinaryContents(contents []byte) bool {
 	return isBinary
 }
 
+// PromptGists prompts the user to select a gist from a list.
 func PromptGists(prompter prompter.Prompter, client *http.Client, host string, cs *iostreams.ColorScheme) (gist *Gist, err error) {
 	gists, err := ListGists(client, host, 10, nil, false, "all")
 	if err != nil {
@@ -248,6 +260,7 @@ func PromptGists(prompter prompter.Prompter, client *http.Client, host string, c
 	return &gists[result], nil
 }
 
+// GetRawGistFile fetches the full raw content of a gist file by URL.
 func GetRawGistFile(httpClient *http.Client, rawURL string) (string, error) {
 	req, err := http.NewRequest("GET", rawURL, nil)
 	if err != nil {
diff --git a/pkg/cmd/gist/view/view.go b/pkg/cmd/gist/view/view.go
index 9eb906cde..66eec2898 100644
--- a/pkg/cmd/gist/view/view.go
+++ b/pkg/cmd/gist/view/view.go
@@ -21,6 +21,7 @@ type browser interface {
 	Browse(string) error
 }
 
+// ViewOptions holds the options for the gist view command.
 type ViewOptions struct {
 	IO         *iostreams.IOStreams
 	Config     func() (gh.Config, error)
@@ -35,6 +36,7 @@ type ViewOptions struct {
 	ListFiles bool
 }
 
+// NewCmdView creates the gist view command.
 func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Command {
 	opts := &ViewOptions{
 		IO:         f.IOStreams,