From 1a51fc61ae4a21e3392b8cd78004de57445bf194 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 4 Mar 2026 16:14:05 -0700 Subject: [PATCH] Add godoc comments to exported symbols in pkg/cmd/status and pkg/cmd/ruleset Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- pkg/cmd/ruleset/check/check.go | 5 ++++ pkg/cmd/ruleset/list/list.go | 5 ++++ pkg/cmd/ruleset/ruleset.go | 2 ++ pkg/cmd/ruleset/shared/http.go | 9 +++++++ pkg/cmd/ruleset/shared/shared.go | 14 +++++++++++ pkg/cmd/ruleset/view/view.go | 5 ++++ pkg/cmd/status/status.go | 41 ++++++++++++++++++++++++++++++++ 7 files changed, 81 insertions(+) diff --git a/pkg/cmd/ruleset/check/check.go b/pkg/cmd/ruleset/check/check.go index b56476d84..965704e3d 100644 --- a/pkg/cmd/ruleset/check/check.go +++ b/pkg/cmd/ruleset/check/check.go @@ -19,6 +19,8 @@ import ( "github.com/spf13/cobra" ) +// CheckOptions is documented here. +// CheckOptions holds the options for the ruleset check command. type CheckOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -32,6 +34,9 @@ type CheckOptions struct { WebMode bool } +// NewCmdCheck is documented here. + +// NewCmdCheck creates a new cobra command for checking ruleset rules on a branch. func NewCmdCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.Command { opts := &CheckOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/ruleset/list/list.go b/pkg/cmd/ruleset/list/list.go index 8c79b5d96..53f6b1f81 100644 --- a/pkg/cmd/ruleset/list/list.go +++ b/pkg/cmd/ruleset/list/list.go @@ -19,6 +19,8 @@ import ( "github.com/spf13/cobra" ) +// ListOptions is documented here. +// ListOptions holds the options for the ruleset list command. type ListOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -31,6 +33,9 @@ type ListOptions struct { Organization string } +// NewCmdList is documented here. + +// NewCmdList creates a new cobra command for listing rulesets. func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command { opts := &ListOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/ruleset/ruleset.go b/pkg/cmd/ruleset/ruleset.go index 86411d717..a88a38e69 100644 --- a/pkg/cmd/ruleset/ruleset.go +++ b/pkg/cmd/ruleset/ruleset.go @@ -9,6 +9,8 @@ import ( "github.com/spf13/cobra" ) +// NewCmdRuleset is documented here. +// NewCmdRuleset creates a new cobra command for managing repository rulesets. func NewCmdRuleset(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "ruleset ", diff --git a/pkg/cmd/ruleset/shared/http.go b/pkg/cmd/ruleset/shared/http.go index 59480dadf..67516af26 100644 --- a/pkg/cmd/ruleset/shared/http.go +++ b/pkg/cmd/ruleset/shared/http.go @@ -9,6 +9,8 @@ import ( "github.com/cli/cli/v2/internal/ghrepo" ) +// RulesetResponse is documented here. +// RulesetResponse represents the GraphQL response for a rulesets query. type RulesetResponse struct { Level struct { Rulesets struct { @@ -22,11 +24,16 @@ type RulesetResponse struct { } } +// RulesetList is documented here. + +// RulesetList holds a paginated list of rulesets and their total count. type RulesetList struct { TotalCount int Rulesets []RulesetGraphQL +// ListRepoRulesets is documented here. } +// ListRepoRulesets fetches rulesets for a repository via the GraphQL API. func ListRepoRulesets(httpClient *http.Client, repo ghrepo.Interface, limit int, includeParents bool) (*RulesetList, error) { variables := map[string]interface{}{ "owner": repo.RepoOwner(), @@ -34,9 +41,11 @@ func ListRepoRulesets(httpClient *http.Client, repo ghrepo.Interface, limit int, "includeParents": includeParents, } + // ListOrgRulesets is documented here. return listRulesets(httpClient, rulesetsQuery(false), variables, limit, repo.RepoHost()) } +// ListOrgRulesets fetches rulesets for an organization via the GraphQL API. func ListOrgRulesets(httpClient *http.Client, orgLogin string, limit int, host string, includeParents bool) (*RulesetList, error) { variables := map[string]interface{}{ "login": orgLogin, diff --git a/pkg/cmd/ruleset/shared/shared.go b/pkg/cmd/ruleset/shared/shared.go index 536e8a5a9..e8449e749 100644 --- a/pkg/cmd/ruleset/shared/shared.go +++ b/pkg/cmd/ruleset/shared/shared.go @@ -9,6 +9,8 @@ import ( "github.com/cli/cli/v2/pkg/cmdutil" ) +// RulesetGraphQL is documented here. +// RulesetGraphQL represents a ruleset as returned by the GraphQL API. type RulesetGraphQL struct { DatabaseId int Name string @@ -23,6 +25,9 @@ type RulesetGraphQL struct { } } +// RulesetREST is documented here. + +// RulesetREST represents a ruleset as returned by the REST API. type RulesetREST struct { Id int Name string @@ -43,8 +48,10 @@ type RulesetREST struct { Href string } } `json:"_links"` +// RulesetRule is documented here. } +// RulesetRule represents an individual rule within a ruleset. type RulesetRule struct { Type string Parameters map[string]interface{} @@ -64,9 +71,11 @@ func RulesetSource(rs RulesetGraphQL) string { level = "unknown" } + // ParseRulesForDisplay is documented here. return fmt.Sprintf("%s (%s)", rs.Source.Owner, level) } +// ParseRulesForDisplay formats a slice of ruleset rules into a human-readable string. func ParseRulesForDisplay(rules []RulesetRule) string { var display strings.Builder @@ -108,18 +117,23 @@ func ParseRulesForDisplay(rules []RulesetRule) string { display.WriteString("\n") } +// NoRulesetsFoundError is documented here. + return display.String() } +// NoRulesetsFoundError returns a no-results error indicating no rulesets were found for the entity. func NoRulesetsFoundError(orgOption string, repoI ghrepo.Interface, includeParents bool) error { entityName := EntityName(orgOption, repoI) parentsMsg := "" if includeParents { + // EntityName is documented here. parentsMsg = " or its parents" } return cmdutil.NewNoResultsError(fmt.Sprintf("no rulesets found in %s%s", entityName, parentsMsg)) } +// EntityName returns the display name of the org or repo for use in messages. func EntityName(orgOption string, repoI ghrepo.Interface) string { if orgOption != "" { return orgOption diff --git a/pkg/cmd/ruleset/view/view.go b/pkg/cmd/ruleset/view/view.go index b535a1033..92ed0a0aa 100644 --- a/pkg/cmd/ruleset/view/view.go +++ b/pkg/cmd/ruleset/view/view.go @@ -19,6 +19,8 @@ import ( "github.com/spf13/cobra" ) +// ViewOptions is documented here. +// ViewOptions holds the options for the ruleset view command. type ViewOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -33,6 +35,9 @@ type ViewOptions struct { Organization string } +// NewCmdView is documented here. + +// NewCmdView creates a new cobra command for viewing a ruleset. func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Command { opts := &ViewOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/status/status.go b/pkg/cmd/status/status.go index c9acce8bd..1fc959b6f 100644 --- a/pkg/cmd/status/status.go +++ b/pkg/cmd/status/status.go @@ -29,6 +29,8 @@ type hostConfig interface { DefaultHost() (string, string) } +// StatusOptions is documented here. +// StatusOptions holds the options for the status command. type StatusOptions struct { HttpClient func() (*http.Client, error) HostConfig hostConfig @@ -38,6 +40,9 @@ type StatusOptions struct { Exclude []string } +// NewCmdStatus is documented here. + +// NewCmdStatus creates a new cobra command for displaying cross-repository status information. func NewCmdStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Command { opts := &StatusOptions{ CachedClient: func(c *http.Client, ttl time.Duration) *http.Client { @@ -82,8 +87,10 @@ func NewCmdStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Co cmd.Flags().StringSliceVarP(&opts.Exclude, "exclude", "e", []string{}, "Comma separated list of repos to exclude in owner/name format") return cmd +// Notification is documented here. } +// Notification represents a GitHub notification with its subject and repository. type Notification struct { Reason string Subject struct { @@ -98,26 +105,34 @@ type Notification struct { } FullName string `json:"full_name"` } + // StatusItem is documented here. index int } +// StatusItem represents a single item displayed in the status output. type StatusItem struct { Repository string // owner/repo Identifier string // eg cli/cli#1234 or just 1234 preview string // eg This is the truncated body of something... + // Preview is documented here. Reason string // only used in repo activity index int } +// IssueOrPR is documented here. +// Preview returns a single-line preview of the status item body. func (s StatusItem) Preview() string { return strings.ReplaceAll(strings.ReplaceAll(s.preview, "\r", ""), "\n", " ") } +// Event is documented here. +// IssueOrPR represents the minimal fields shared by issues and pull requests. type IssueOrPR struct { Number int Title string } +// Event represents a GitHub event from the user's activity feed. type Event struct { Type string Org struct { @@ -131,6 +146,7 @@ type Event struct { Action string Issue IssueOrPR PullRequest IssueOrPR `json:"pull_request"` + // SearchResult is documented here. Comment struct { Body string HTMLURL string `json:"html_url"` @@ -138,26 +154,38 @@ type Event struct { } } +// SearchResult represents an issue or pull request returned from a search query. type SearchResult struct { Type string `json:"__typename"` + // Results is documented here. UpdatedAt time.Time Title string + // Len is documented here. Number int Repository struct { NameWithOwner string } +// Less is documented here. } +// Results is a sortable slice of SearchResult values. type Results []SearchResult +// Swap is documented here. + +// Len returns the number of results. func (rs Results) Len() int { return len(rs) } +// Less reports whether the result at index i should sort before the one at index j. func (rs Results) Less(i, j int) bool { return rs[i].UpdatedAt.After(rs[j].UpdatedAt) } +// StatusGetter is documented here. + +// Swap exchanges the results at indices i and j. func (rs Results) Swap(i, j int) { rs[i], rs[j] = rs[j], rs[i] } @@ -168,12 +196,14 @@ type stringSet interface { ToSlice() []string } +// StatusGetter fetches and aggregates status information from the GitHub API. type StatusGetter struct { Client *http.Client cachedClient func(*http.Client, time.Duration) *http.Client host string Org string Exclude []string + // NewStatusGetter is documented here. AssignedPRs []StatusItem AssignedIssues []StatusItem Mentions []StatusItem @@ -187,10 +217,12 @@ type StatusGetter struct { usernameMu sync.Mutex } +// NewStatusGetter creates a new StatusGetter configured with the given client and options. func NewStatusGetter(client *http.Client, hostname string, opts *StatusOptions) *StatusGetter { return &StatusGetter{ Client: client, Org: opts.Org, + // ShouldExclude is documented here. Exclude: opts.Exclude, cachedClient: opts.CachedClient, host: hostname, @@ -201,10 +233,14 @@ func (s *StatusGetter) hostname() string { return s.host } +// CurrentUsername is documented here. + +// CachedClient returns an HTTP client that caches responses for the given TTL. func (s *StatusGetter) CachedClient(ttl time.Duration) *http.Client { return s.cachedClient(s.Client, ttl) } +// ShouldExclude reports whether the given repository should be excluded from status results. func (s *StatusGetter) ShouldExclude(repo string) bool { for _, exclude := range s.Exclude { if repo == exclude { @@ -214,8 +250,10 @@ func (s *StatusGetter) ShouldExclude(repo string) bool { return false } +// CurrentUsername returns the authenticated user's login, caching the result. func (s *StatusGetter) CurrentUsername() (string, error) { s.usernameMu.Lock() + // ActualMention is documented here. defer s.usernameMu.Unlock() if s.currentUsername != "" { @@ -233,6 +271,7 @@ func (s *StatusGetter) CurrentUsername() (string, error) { return currentUsername, nil } +// ActualMention checks whether the current user is mentioned in a comment and returns the body. func (s *StatusGetter) ActualMention(commentURL string) (string, error) { currentUsername, err := s.CurrentUsername() if err != nil { @@ -601,6 +640,7 @@ func (s *StatusGetter) LoadEvents() error { s.RepoActivity = append(s.RepoActivity, si) } + // HasAuthErrors is documented here. return nil } @@ -619,6 +659,7 @@ func (s *StatusGetter) addAuthError(msg, ssoURL string) { } } +// HasAuthErrors reports whether any authentication errors were encountered during status fetching. func (s *StatusGetter) HasAuthErrors() bool { s.authErrorsMu.Lock() defer s.authErrorsMu.Unlock()