chore: Add new lint rule to make sure exported names documented

.golangci.yml

@@ -84,6 +84,11 @@ linters:
         - name: error-return
         - name: error-strings
         - name: errorf
+        - name: exported
+          arguments:
+            - disableChecksOnConstants
+            - disableChecksOnVariables
+            - disableStutteringCheck
         - name: filename-format
           arguments:
             - ^[_a-z][_a-z0-9]*.go$

github/actions_workflow_runs.go

@@ -106,6 +106,7 @@ type PendingDeploymentsRequest struct {
 	Comment string `json:"comment"`
 }
 
+// ReferencedWorkflow represents a referenced workflow in a workflow run.
 type ReferencedWorkflow struct {
 	Path *string `json:"path,omitempty"`
 	SHA  *string `json:"sha,omitempty"`

github/apps.go

@@ -56,6 +56,8 @@ type InstallationTokenOptions struct {
 	Permissions *InstallationPermissions `json:"permissions,omitempty"`
 }
 
+// InstallationTokenListRepoOptions allow restricting a token's access to a list of all repositories in an installation.
+// It differs from InstallationTokenOptions as a parameter which does not omit RepositoryIDs if that field is nil or an empty array.
 type InstallationTokenListRepoOptions struct {
 	// The IDs of the repositories that the installation token can access.
 	// Providing repository IDs restricts the access of an installation token to specific repositories.

github/copilot.go

@@ -185,6 +185,7 @@ type CopilotMetrics struct {
 	CopilotDotcomPullRequests *CopilotDotcomPullRequests `json:"copilot_dotcom_pull_requests,omitempty"`
 }
 
+// UnmarshalJSON implements the json.Unmarshaler interface.
 func (cp *CopilotSeatDetails) UnmarshalJSON(data []byte) error {
 	// Using an alias to avoid infinite recursion when calling json.Unmarshal
 	type alias CopilotSeatDetails

github/dependency_graph.go

@@ -10,6 +10,10 @@ import (
 	"fmt"
 )
 
+// DependencyGraphService handles communication with the dependency graph
+// related methods of the GitHub API.
+//
+// GitHub API docs: https://docs.github.com/rest/dependency-graph
 type DependencyGraphService service
 
 // SBOM represents a software bill of materials, which describes the

github/git_commits.go

@@ -37,6 +37,7 @@ type MessageSigner interface {
 // MessageSignerFunc is a single function implementation of MessageSigner.
 type MessageSignerFunc func(w io.Writer, r io.Reader) error
 
+// Sign implements the MessageSigner interface for MessageSignerFunc.
 func (f MessageSignerFunc) Sign(w io.Writer, r io.Reader) error {
 	return f(w, r)
 }
@@ -110,6 +111,8 @@ type createCommit struct {
 	Signature *string       `json:"signature,omitempty"`
 }
 
+// CreateCommitOptions specifies optional parameters to creates
+// a new commit in a repository.
 type CreateCommitOptions struct {
 	// CreateCommit will sign the commit with this signer. See MessageSigner doc for more details.
 	// Ignored on commits where Verification.Signature is defined.

github/git_trees.go

@@ -58,6 +58,7 @@ type treeEntryWithFileDelete struct {
 	URL     *string `json:"url,omitempty"`
 }
 
+// MarshalJSON implements the json.Marshaler interface.
 func (t *TreeEntry) MarshalJSON() ([]byte, error) {
 	if t.SHA == nil && t.Content == nil {
 		return json.Marshal(struct {

github/github.go

@@ -1390,6 +1390,7 @@ func (e *Error) Error() string {
 		e.Code, e.Field, e.Resource)
 }
 
+// UnmarshalJSON implements the json.Unmarshaler interface.
 func (e *Error) UnmarshalJSON(data []byte) error {
 	type aliasError Error // avoid infinite recursion by using type alias.
 	if err := json.Unmarshal(data, (*aliasError)(e)); err != nil {
@@ -1492,6 +1493,7 @@ func parseBoolResponse(err error) (bool, error) {
 	return false, err
 }
 
+// RateLimitCategory represents the enumeration of rate limit categories.
 type RateLimitCategory uint8
 
 const (

github/orgs_audit_log.go

@@ -56,6 +56,7 @@ type AuditEntry struct {
 	AdditionalFields map[string]any `json:"-"`
 }
 
+// UnmarshalJSON implements the json.Unmarshaler interface.
 func (a *AuditEntry) UnmarshalJSON(data []byte) error {
 	type entryAlias AuditEntry
 	var v entryAlias
@@ -89,6 +90,7 @@ func (a *AuditEntry) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// MarshalJSON implements the json.Marshaler interface.
 func (a *AuditEntry) MarshalJSON() ([]byte, error) {
 	type entryAlias AuditEntry
 	v := entryAlias(*a)

github/repos_tags.go

@@ -22,8 +22,9 @@ type tagProtectionRequest struct {
 	Pattern string `json:"pattern"`
 }
 
-// Deprecated: ListTagProtection lists tag protection of the specified repository.
-// Deprecation notice: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#get-all-repository-rulesets
+// ListTagProtection lists tag protection of the specified repository.
+//
+// Deprecated: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#get-all-repository-rulesets
 //
 // GitHub API docs: https://docs.github.com/rest/repos/tags#closing-down---list-tag-protection-states-for-a-repository
 //
@@ -45,8 +46,9 @@ func (s *RepositoriesService) ListTagProtection(ctx context.Context, owner, repo
 	return tagProtections, resp, nil
 }
 
-// Deprecated: CreateTagProtection creates the tag protection of the specified repository.
-// Deprecation notice: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#create-a-repository-ruleset
+// CreateTagProtection creates the tag protection of the specified repository.
+//
+// Deprecated: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#create-a-repository-ruleset
 //
 // GitHub API docs: https://docs.github.com/rest/repos/tags#closing-down---create-a-tag-protection-state-for-a-repository
 //
@@ -68,8 +70,9 @@ func (s *RepositoriesService) CreateTagProtection(ctx context.Context, owner, re
 	return tagProtection, resp, nil
 }
 
-// Deprecated: DeleteTagProtection deletes a tag protection from the specified repository.
-// Deprecation notice: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#delete-a-repository-ruleset
+// DeleteTagProtection deletes a tag protection from the specified repository.
+//
+// Deprecated: This operation is deprecated and will be removed after August 30, 2024. Use the "Repository Rulesets" endpoint instead: https://docs.github.com/rest/repos/rules#delete-a-repository-ruleset
 //
 // GitHub API docs: https://docs.github.com/rest/repos/tags#closing-down---delete-a-tag-protection-state-for-a-repository
 //

github/search.go

@@ -92,6 +92,7 @@ type TopicsSearchResult struct {
 	Topics            []*TopicResult `json:"items,omitempty"`
 }
 
+// TopicResult represents a topic search result.
 type TopicResult struct {
 	Name             *string    `json:"name,omitempty"`
 	DisplayName      *string    `json:"display_name,omitempty"`

github/security_advisories.go

@@ -11,6 +11,10 @@ import (
 	"fmt"
 )
 
+// SecurityAdvisoriesService handles communication with the security advisories
+// related methods of the GitHub API.
+//
+// GitHub API docs: https://docs.github.com/rest/security-advisories
 type SecurityAdvisoriesService service
 
 // SecurityAdvisorySubmission represents the Security Advisory Submission.

tools/sliceofpointers/sliceofpointers.go

@@ -21,13 +21,15 @@ func init() {
 	register.Plugin("sliceofpointers", New)
 }
 
+// SliceOfPointersPlugin is a custom linter plugin for golangci-lint.
 type SliceOfPointersPlugin struct{}
 
 // New returns an analysis.Analyzer to use with golangci-lint.
 func New(_ any) (register.LinterPlugin, error) {
 	return &SliceOfPointersPlugin{}, nil
 }
 
+// BuildAnalyzers builds the analyzers for the SliceOfPointersPlugin.
 func (f *SliceOfPointersPlugin) BuildAnalyzers() ([]*analysis.Analyzer, error) {
 	return []*analysis.Analyzer{
 		{
@@ -38,6 +40,7 @@ func (f *SliceOfPointersPlugin) BuildAnalyzers() ([]*analysis.Analyzer, error) {
 	}, nil
 }
 
+// GetLoadMode returns the load mode for the SliceOfPointersPlugin.
 func (f *SliceOfPointersPlugin) GetLoadMode() string {
 	return register.LoadModeSyntax
 }