[GitHub] [trafficcontrol] ocket8888 opened a new pull request #6040: Add/Update/Correct GoDoc comments under `lib/`

[GitBox <gi...@apache.org>]

ocket8888 opened a new pull request #6040:
URL: https://github.com/apache/trafficcontrol/pull/6040


   ## What does this PR (Pull Request) do?
   - [x] This PR is not related to any Issue
   
   This PR modifies the packages:
   
   - `github.com/apache/trafficcontrol/lib/go-tc`
   - `github.com/apache/trafficcontrol/lib/go-tc/tovalidate`
   - `github.com/apache/trafficcontrol/lib/go-nagios`
   
   This PR ensures that each modified package
   
   - Has a GoDoc comment for the package, and that comment is properly recognized (on master enum.go's comment is currently being picked up as the package documentation by some tools, because enum.go is encountered alphabetically before doc.go)
   - Has a GoDoc comment for every exported symbol
   - Uses complete sentences with proper capitalization and punctuation in GoDoc comments
   - Begins every GoDoc comment with either an optional article followed by the name of the documented symbol or the word "Package" followed by the name of the documented package.
   - Has no GoDoc comments of the form `// SymbolName ...` where `...` is literal.
   
   This PR also adds deprecation notices to many structures used only in nesting (i.e. they are APIv1 structures that survive only because removing them is a breaking change to more recent structures) or used in deprecated API versions (2 and 3).
   
   There should be no actual code changes from this PR, but it does move imports around in affected files if necessary to match the pattern:
   
   ```go
   package packageName
   
   // License header
   
   import (
       "package names for import"
   )
   ```
   
   To avoid adding GoDoc comments for things that should just be removed, this PR depends on #6038 and so is a draft until that is merged.
   
   ## Which Traffic Control components are affected by this PR?
   - Documentation (GoDoc comments)
   
   ## What is the best way to verify this PR?
   I used the command
   ```bash
   golangci-lint run -c ./.golangci.yml 2>&1 | grep -E '^go-' | grep -v 'move short variable' | grep -v 'error strings should not be capitalized' | grep -v "don't use generic names such as" | grep -vE 'struct field `\w+` should be' | grep -v 'block ends with a' | grep -v 'errors.New(fmt.Sprintf(...))' | grep -vE 'receiver name \w+ should be consistent' | grep -v 'should not use basic type string as key in context.WithValue' | grep -vE 'var `\w+` should be `\w+`'
   ```
   from within `lib/` with this in `./.golangci.yml`:
   
   <details><summary>Click to expand</summary>
   
   ```yaml
   run:
     concurrency: 4
     timeout: 5m
     issues-exit-code: 0 # TODO: once all enabled linters are satisfied
     tests: false
     skip-dirs:
       - ^experimental.*($|/)
       - go-atscfg
       - go-rfc
       - go-log
       - go-util
     skip-dirs-use-default: true
   
     output:
       format: colored-line-number
       print-issued-lines: true
       print-linter-name: true
   
   issues:
     max-issues-per-linter: 0
     max-same-issues: 0
     exclude-use-default: false
   
     include:
       - EXC0002
       - EXC0011
   
   linters:
     disable-all: true
     enable:
       - asciicheck
       - bodyclose
       - deadcode
       - depguard
       - dogsled
       - durationcheck
       - exportloopref
       - gochecknoinits
       - godot
       - gofmt
       - golint
       - gomodguard
       - goprintffuncname
       - gosec
       - govet
       - ifshort
       - importas
       - ineffassign
       - makezero
       - misspell
       - nakedret
       - noctx
       - nolintlint
       - paralleltest
       - predeclared
       - revive
       - scopelint
       - sqlclosecheck
       - structcheck
       - testpackage
       - thelper
       - tparallel
       - typecheck
       - unparam
       - unused
       - varcheck
   ```
   
   </details>
   
   ... that should output nothing (but it will exit with a failure because `grep` finds no matching lines.
   
   Then to find things like `// Foo ...` I did
   ```bash
   grep -RE '^// \w+ \.\.\.' .
   ```
   
   ... also within `lib/`, which should also output no lines (and exit failure b/c `grep`).
   
   ## The following criteria are ALL met by this PR
   - [x] Tests are unnecessary
   - [x] This PR includes documentation (sorta)
   - [x] An update to CHANGELOG.md is not necessary
   - [x] This PR includes any and all required license headers
   - [x] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY**


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] zrhoffman merged pull request #6040: Add/Update/Correct GoDoc comments under `lib/`

[GitBox <gi...@apache.org>]

zrhoffman merged pull request #6040:
URL: https://github.com/apache/trafficcontrol/pull/6040


   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org