Add godoc comments to exported symbols in pkg/cmd/agent-task and pkg/cmd/search

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

pkg/cmd/agent-task/capi/client.go

@@ -54,6 +54,8 @@ func newCAPITransport(token string, rp http.RoundTripper) *capiTransport {
 	}
 }
 
+// RoundTrip is documented here.
+// RoundTrip adds authorization and integration headers before delegating to the underlying transport.
 func (ct *capiTransport) RoundTrip(req *http.Request) (*http.Response, error) {
 	req.Header.Set("Authorization", "Bearer "+ct.token)
 

pkg/cmd/agent-task/capi/job.go

@@ -34,17 +34,24 @@ type Job struct {
 	ErrorInfo *JobError `json:"error,omitempty"`
 }
 
+// JobActor is documented here.
+// JobActor represents the user who initiated an agent task job.
 type JobActor struct {
 	ID    int    `json:"id"`
 	Login string `json:"login"`
 }
 
+// JobPullRequest is documented here.
+
+// JobPullRequest represents the pull request associated with an agent task job.
 type JobPullRequest struct {
 	ID      int    `json:"id"`
 	Number  int    `json:"number"`
 	BaseRef string `json:"base_ref,omitempty"`
+// JobError is documented here.
 }
 
+// JobError describes an error that occurred during an agent task job.
 type JobError struct {
 	Message            string `json:"message"`
 	ResponseStatusCode int    `json:"response_status_code,string"`

pkg/cmd/agent-task/capi/sessions.go

@@ -20,10 +20,15 @@ import (
 	"github.com/vmihailenco/msgpack/v5"
 )
 
+// AgentsHomeURL is documented here.
+// AgentsHomeURL is the URL for the Copilot agents home page.
 const AgentsHomeURL = "https://github.com/copilot/agents"
 
 var defaultSessionsPerPage = 50
 
+// ErrSessionNotFound is documented here.
+
+// ErrSessionNotFound is returned when a session cannot be found.
 var ErrSessionNotFound = errors.New("not found")
 
 // session is an in-flight agent task
@@ -95,8 +100,10 @@ type Session struct {
 
 	PullRequest *api.PullRequest
 	User        *api.GitHubUser
+// SessionError is documented here.
 }
 
+// SessionError represents an error returned by a session.
 type SessionError struct {
 	Code    string
 	Message string

pkg/cmd/agent-task/create/create.go

@@ -46,6 +46,8 @@ func defaultLogRenderer() shared.LogRenderer {
 	return shared.NewLogRenderer()
 }
 
+// NewCmdCreate is documented here.
+// NewCmdCreate returns a cobra command for creating a new agent task.
 func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Command {
 	opts := &CreateOptions{
 		IO:          f.IOStreams,

pkg/cmd/agent-task/shared/capi.go

@@ -15,6 +15,8 @@ const uuidPattern = `[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}
 var sessionIDRegexp = regexp.MustCompile(fmt.Sprintf("^%s$", uuidPattern))
 var agentSessionURLRegexp = regexp.MustCompile(fmt.Sprintf("^/agent-sessions/(%s)$", uuidPattern))
 
+// CapiClientFunc is documented here.
+// CapiClientFunc returns a factory function that creates an authenticated Copilot API client.
 func CapiClientFunc(f *cmdutil.Factory) func() (capi.CapiClient, error) {
 	return func() (capi.CapiClient, error) {
 		cfg, err := f.Config()
@@ -34,6 +36,9 @@ func CapiClientFunc(f *cmdutil.Factory) func() (capi.CapiClient, error) {
 	}
 }
 
+// IsSessionID is documented here.
+
+// IsSessionID reports whether s is a valid session UUID.
 func IsSessionID(s string) bool {
 	return sessionIDRegexp.MatchString(s)
 }

pkg/cmd/agent-task/shared/display.go

@@ -48,8 +48,13 @@ func SessionStateString(state string) string {
 	}
 }
 
+// ColorFunc is documented here.
+// ColorFunc is a function that applies terminal color formatting to a string.
 type ColorFunc func(string) string
 
+// SessionSymbol is documented here.
+
+// SessionSymbol returns a status icon for the given session state.
 func SessionSymbol(cs *iostreams.ColorScheme, state string) string {
 	noColor := func(s string) string { return s }
 	switch state {

pkg/cmd/agent-task/shared/log.go

@@ -15,6 +15,8 @@ import (
 
 //go:generate moq -rm -out log_mock.go . LogRenderer
 
+// LogRenderer is documented here.
+// LogRenderer renders agent task log output.
 type LogRenderer interface {
 	Follow(fetcher func() ([]byte, error), w io.Writer, io *iostreams.IOStreams) error
 	Render(logs []byte, w io.Writer, io *iostreams.IOStreams) (stop bool, err error)
@@ -22,6 +24,9 @@ type LogRenderer interface {
 
 type logRenderer struct{}
 
+// NewLogRenderer is documented here.
+
+// NewLogRenderer creates a new LogRenderer instance.
 func NewLogRenderer() LogRenderer {
 	return &logRenderer{}
 }

pkg/cmd/agent-task/view/view.go

@@ -29,6 +29,8 @@ const (
 	defaultLogPollInterval = 5 * time.Second
 )
 
+// ViewOptions is documented here.
+// ViewOptions holds the options for the agent-task view command.
 type ViewOptions struct {
 	IO         *iostreams.IOStreams
 	BaseRepo   func() (ghrepo.Interface, error)
@@ -54,6 +56,9 @@ func defaultLogRenderer() shared.LogRenderer {
 	return shared.NewLogRenderer()
 }
 
+// NewCmdView is documented here.
+
+// NewCmdView returns a cobra command for viewing an agent task.
 func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Command {
 	opts := &ViewOptions{
 		IO:          f.IOStreams,

pkg/cmd/search/code/code.go

@@ -16,6 +16,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CodeOptions is documented here.
+// CodeOptions holds the options for the search code command.
 type CodeOptions struct {
 	Browser  browser.Browser
 	Config   func() (gh.Config, error)
@@ -26,6 +28,9 @@ type CodeOptions struct {
 	WebMode  bool
 }
 
+// NewCmdCode is documented here.
+
+// NewCmdCode returns a cobra command for searching code on GitHub.
 func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Command {
 	opts := &CodeOptions{
 		Browser: f.Browser,

pkg/cmd/search/commits/commits.go

@@ -15,6 +15,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CommitsOptions is documented here.
+// CommitsOptions holds the options for the search commits command.
 type CommitsOptions struct {
 	Browser  browser.Browser
 	Exporter cmdutil.Exporter
@@ -25,6 +27,9 @@ type CommitsOptions struct {
 	WebMode  bool
 }
 
+// NewCmdCommits is documented here.
+
+// NewCmdCommits returns a cobra command for searching commits on GitHub.
 func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra.Command {
 	var order string
 	var sort string

pkg/cmd/search/issues/issues.go

@@ -10,6 +10,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdIssues is documented here.
+// NewCmdIssues returns a cobra command for searching issues on GitHub.
 func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobra.Command {
 	var locked, includePrs bool
 	var noAssignee, noLabel, noMilestone, noProject bool

pkg/cmd/search/prs/prs.go

@@ -11,6 +11,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdPrs is documented here.
+// NewCmdPrs returns a cobra command for searching pull requests on GitHub.
 func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobra.Command {
 	var locked, merged bool
 	var noAssignee, noLabel, noMilestone, noProject bool

pkg/cmd/search/repos/repos.go

@@ -16,6 +16,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// ReposOptions is documented here.
+// ReposOptions holds the options for the search repos command.
 type ReposOptions struct {
 	Browser  browser.Browser
 	Exporter cmdutil.Exporter
@@ -26,6 +28,9 @@ type ReposOptions struct {
 	WebMode  bool
 }
 
+// NewCmdRepos is documented here.
+
+// NewCmdRepos returns a cobra command for searching repositories on GitHub.
 func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Command {
 	var order string
 	var sort string

pkg/cmd/search/search.go

@@ -12,6 +12,8 @@ import (
 	searchReposCmd "github.com/cli/cli/v2/pkg/cmd/search/repos"
 )
 
+// NewCmdSearch is documented here.
+// NewCmdSearch returns a cobra command for searching GitHub resources.
 func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search <command>",

pkg/cmd/search/shared/shared.go

@@ -15,6 +15,8 @@ import (
 	"github.com/cli/cli/v2/pkg/search"
 )
 
+// EntityType is documented here.
+// EntityType represents the kind of entity to search for (issues, pull requests, or both).
 type EntityType int
 
 const (
@@ -22,22 +24,32 @@ const (
 	// https://docs.github.com/en/rest/reference/search
 	SearchMaxResults = 1000
 
+// Both is documented here.
+
+	// Issues is documented here.
+	// Both searches for issues and pull requests.
 	Both EntityType = iota
+	// Issues searches only for issues.
 	Issues
+	// IssuesOptions is documented here.
+	// PullRequests searches only for pull requests.
 	PullRequests
 )
 
+// IssuesOptions holds the options for searching issues and pull requests.
 type IssuesOptions struct {
 	Browser  browser.Browser
 	Entity   EntityType
 	Exporter cmdutil.Exporter
 	IO       *iostreams.IOStreams
 	Now      time.Time
+	// Searcher is documented here.
 	Query    search.Query
 	Searcher search.Searcher
 	WebMode  bool
 }
 
+// Searcher creates a new search.Searcher using the factory's configuration.
 func Searcher(f *cmdutil.Factory) (search.Searcher, error) {
 	cfg, err := f.Config()
 	if err != nil {
@@ -50,11 +62,14 @@ func Searcher(f *cmdutil.Factory) (search.Searcher, error) {
 		return nil, err
 	}
 
+// SearchIssues is documented here.
+
 	detector := fd.NewDetector(client, host)
 
 	return search.NewSearcher(client, host, detector), nil
 }
 
+// SearchIssues executes a search for issues or pull requests and displays the results.
 func SearchIssues(opts *IssuesOptions) error {
 	io := opts.IO
 	if opts.WebMode {