Lint godoc comments (#2972)

Author: WillAbides

.golangci.yml

@@ -18,10 +18,13 @@ linters:
 linters-settings:
   gosec:
     excludes:
+      # duplicates errcheck
+      - G104
       # performance issue: see https://github.com/golangci/golangci-lint/issues/4039
       # and https://github.com/securego/gosec/issues/1007
       - G602
 issues:
+  exclude-use-default: false
   exclude-rules:
     - linters:
         - dupl
@@ -38,3 +41,13 @@ issues:
     # We need to use sha1 for validating signatures
     - linters: [ gosec ]
       text: 'G505: Blocklisted import crypto/sha1: weak cryptographic primitive'
+
+    # This is adapted from golangci-lint's default exclusions. It disables linting for error checks on
+    # os.RemoveAll and any function ending in "Close".
+    - linters: [ errcheck ]
+      text: Error return value of .(.*Close|os\.Remove(All)?). is not checked
+
+    # We don't care about file inclusion via variable in examples or internal tools.
+    - linters: [ gosec ]
+      text: 'G304: Potential file inclusion via variable'
+      path: '^(example|update-urls)\/'

github/actions_permissions_enterprise.go

@@ -10,7 +10,7 @@ import (
 	"fmt"
 )
 
-// ActionsEnabledOnEnterpriseOrgs represents all the repositories in an enterprise for which Actions is enabled.
+// ActionsEnabledOnEnterpriseRepos represents all the repositories in an enterprise for which Actions is enabled.
 type ActionsEnabledOnEnterpriseRepos struct {
 	TotalCount    int             `json:"total_count"`
 	Organizations []*Organization `json:"organizations"`

github/actions_permissions_orgs.go

@@ -145,7 +145,7 @@ func (s *ActionsService) AddEnabledReposInOrg(ctx context.Context, owner string,
 	return resp, nil
 }
 
-// RemoveEnabledRepoInOrg removes a single repository from the list of enabled repos for GitHub Actions in an organization.
+// RemoveEnabledReposInOrg removes a single repository from the list of enabled repos for GitHub Actions in an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/actions/permissions#disable-a-selected-repository-for-github-actions-in-an-organization
 func (s *ActionsService) RemoveEnabledReposInOrg(ctx context.Context, owner string, repositoryID int64) (*Response, error) {

github/codesofconduct.go

@@ -46,7 +46,8 @@ func (s *CodesOfConductService) List(ctx context.Context) ([]*CodeOfConduct, *Re
 	return cs, resp, nil
 }
 
-// ListCodesOfConduct
+// ListCodesOfConduct returns all codes of conduct.
+//
 // Deprecated: Use CodesOfConductService.List instead
 func (c *Client) ListCodesOfConduct(ctx context.Context) ([]*CodeOfConduct, *Response, error) {
 	return c.CodesOfConduct.List(ctx)
@@ -74,7 +75,8 @@ func (s *CodesOfConductService) Get(ctx context.Context, key string) (*CodeOfCon
 	return coc, resp, nil
 }
 
-// GetCodeOfConduct
+// GetCodeOfConduct returns an individual code of conduct.
+//
 // Deprecated: Use CodesOfConductService.Get instead
 func (c *Client) GetCodeOfConduct(ctx context.Context, key string) (*CodeOfConduct, *Response, error) {
 	return c.CodesOfConduct.Get(ctx, key)

github/codespaces.go

@@ -112,7 +112,7 @@ func (s *CodespacesService) ListInRepo(ctx context.Context, owner, repo string,
 	return codespaces, resp, nil
 }
 
-// ListOptions represents the options for listing codespaces for a user.
+// ListCodespacesOptions represents the options for listing codespaces for a user.
 type ListCodespacesOptions struct {
 	ListOptions
 	RepositoryID int64 `url:"repository_id,omitempty"`

github/emojis.go

@@ -30,7 +30,8 @@ func (s *EmojisService) List(ctx context.Context) (map[string]string, *Response,
 	return emoji, resp, nil
 }
 
-// ListEmojis
+// ListEmojis returns the emojis available to use on GitHub.
+//
 // Deprecated: Use EmojisService.List instead
 func (c *Client) ListEmojis(ctx context.Context) (map[string]string, *Response, error) {
 	return c.Emojis.List(ctx)

github/event_types.go

@@ -1069,7 +1069,7 @@ type ArchivedAt struct {
 	To   *Timestamp `json:"to,omitempty"`
 }
 
-// ProjectsV2 represents an item belonging to a project.
+// ProjectV2Item represents an item belonging to a project.
 type ProjectV2Item struct {
 	ID            *int64     `json:"id,omitempty"`
 	NodeID        *string    `json:"node_id,omitempty"`

github/issues.go

@@ -303,7 +303,7 @@ func (s *IssuesService) Edit(ctx context.Context, owner string, repo string, num
 	return i, resp, nil
 }
 
-// Remove a milestone from an issue.
+// RemoveMilestone removes a milestone from an issue.
 //
 // This is a helper method to explicitly update an issue with a `null` milestone, thereby removing it.
 //

github/messages.go

@@ -326,7 +326,7 @@ func ParseWebHook(messageType string, payload []byte) (interface{}, error) {
 	return event.ParsePayload()
 }
 
-// WebhookTypes returns a sorted list of all the known GitHub event type strings
+// MessageTypes returns a sorted list of all the known GitHub event type strings
 // supported by go-github.
 func MessageTypes() []string {
 	types := make([]string, 0, len(eventTypeMapping))

github/meta.go

@@ -87,7 +87,8 @@ func (s *MetaService) Get(ctx context.Context) (*APIMeta, *Response, error) {
 	return meta, resp, nil
 }
 
-// APIMeta
+// APIMeta returns information about GitHub.com.
+//
 // Deprecated: Use MetaService.Get instead.
 func (c *Client) APIMeta(ctx context.Context) (*APIMeta, *Response, error) {
 	return c.Meta.Get(ctx)
@@ -117,7 +118,9 @@ func (s *MetaService) Octocat(ctx context.Context, message string) (string, *Res
 	return buf.String(), resp, nil
 }
 
-// Octocat
+// Octocat returns an ASCII art octocat with the specified message in a speech
+// bubble. If message is empty, a random zen phrase is used.
+//
 // Deprecated: Use MetaService.Octocat instead.
 func (c *Client) Octocat(ctx context.Context, message string) (string, *Response, error) {
 	return c.Meta.Octocat(ctx, message)
@@ -143,7 +146,8 @@ func (s *MetaService) Zen(ctx context.Context) (string, *Response, error) {
 	return buf.String(), resp, nil
 }
 
-// Zen
+// Zen returns a random line from The Zen of GitHub.
+//
 // Deprecated: Use MetaService.Zen instead.
 func (c *Client) Zen(ctx context.Context) (string, *Response, error) {
 	return c.Meta.Zen(ctx)