Add/Update/Correct GoDoc comments on /lib symbols

[ocket8888]

This PR modifies the packages

• github.com/apache/trafficcontrol/lib/go-atscfg
• github.com/apache/trafficcontrol/lib/go-log
• github.com/apache/trafficcontrol/lib/go-rfc
• github.com/apache/trafficcontrol/lib/go-util

This PR ensures that each modified package

• Has a GoDoc comment for the package, and that comment is properly recognized
• 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 some structures used only in deprecated API versions (2 and 3).

There should be only one actual code change from this PR - fixing a misspelling of "occurred" ("occured") -, but it does move imports around in affected files if necessary to match the pattern:

package packageName

// License header

import (
    "package names for import"
)

and possibly moves constants to logical groupings so that a single GoDoc can be written effectively for the group. In at least one case this involved moving a symbol to a different file (but not a different package).

---

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

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+`' | grep -v 'returns unexported type' | grep -v 'should omit 2nd value from range' | grep -v 'by other packages, and that stutters;' | grep -v "don't use ALL_CAPS in Go names; use CamelCase" | grep -v 'regexrevalidatedotconfig.go:36:7: const'

which should output nothing (but exit with a failure because grep found no matches), with the following in ./golangci.yml (under lib/):

Click to expand

run:
  concurrency: 4
  timeout: 5m
  issues-exit-code: 0 # TODO: once all enabled linters are satisfied
  tests: false
  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
    - depguard
    - dogsled
    - durationcheck
    - gochecknoinits
    - godot
    - golint
    - gomodguard
    - govet
    - importas
    - makezero
    - misspell
    - nakedret
    - noctx
    - nolintlint
    - paralleltest
    - predeclared
    - sqlclosecheck
    - structcheck
    - testpackage
    - thelper
    - tparallel
    - typecheck
    - varcheck

Then to find things like // Foo ... I did

grep -RE '^// \w+ \.\.\.' .

... also within lib/, which should also output no lines (and exit failure b/c grep).

PR submission checklist

• This PR has tests
• This PR has documentation
• This PR has a CHANGELOG.md entry
• This PR DOES NOT FIX A SERIOUS SECURITY VULNERABILITY

[codecov]

Codecov Report

Merging #6099 (903041e) into master (40f0b57) will increase coverage by 0.26%.
The diff coverage is 23.07%.

@@             Coverage Diff              @@
##             master    #6099      +/-   ##
============================================
+ Coverage     28.91%   29.18%   +0.26%     
============================================
  Files           600      518      -82     
  Lines         77353    75777    -1576     
  Branches         90      880     +790     
============================================
- Hits          22368    22114     -254     
+ Misses        52892    51786    -1106     
+ Partials       2093     1877     -216     

Flag	Coverage Δ
golib_unit	53.57% <23.07%> (-0.02%)	⬇️
grove_unit	12.02% <ø> (ø)
t3c_generate_unit	?
t3c_unit	5.80% <ø> (-0.12%)	⬇️
traffic_monitor_unit	26.44% <ø> (ø)
traffic_ops_integration	?
traffic_ops_unit	21.67% <ø> (ø)
traffic_portal_v2	74.37% <ø> (?)
traffic_router_unit	?
traffic_stats_unit	10.78% <ø> (ø)
unit_tests	29.18% <23.07%> (+3.43%)	⬆️
v3	?
v4	?
v5	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
lib/go-atscfg/astatsdotconfig.go	0.00% <ø> (ø)
lib/go-atscfg/atscfg.go	51.73% <ø> (ø)
lib/go-atscfg/atsdotrules.go	75.75% <ø> (ø)
lib/go-atscfg/bgfetchdotconfig.go	66.66% <ø> (ø)
lib/go-atscfg/cachedotconfig.go	43.30% <ø> (ø)
lib/go-atscfg/chkconfig.go	80.64% <ø> (ø)
lib/go-atscfg/dropqstringdotconfig.go	55.17% <ø> (ø)
lib/go-atscfg/facts.go	68.42% <ø> (ø)
lib/go-atscfg/headerrewritedotconfig.go	56.83% <ø> (ø)
lib/go-atscfg/hostingdotconfig.go	57.69% <ø> (ø)
... and 44 more

... and 318 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more